[TASK] Overhaul the File structure to fit the new one #356
Conversation
prune unnecessary information.
It is not needed anymore except in rare edge cases.
We currently do not support a generated output of this file and in most cases it was not very usefull.
|
|
||
| - :file:`Documentation/Settings.cfg`. | ||
| * A valid :file:`composer.json` | ||
| * A documentation entry point either for :ref:`Full documentation <full-documentation>` |
There was a problem hiding this comment.
Also a README can hold full documentation (in one file). Would use the word "manual" instead of "full documentation".
| *single file documentation* style, the first being preferred for several | ||
| reasons. | ||
|
|
||
| * reST files have the extension :file:`.rst'. |
There was a problem hiding this comment.
In this chapter "reST" is not explained. Either explain it or link to an explanation.
| The Settings.cfg configuration file allows you to set theme variables, i.e. the | ||
| project title, release version and the like. | ||
| To render a complete documentation manual you need a folder called | ||
| :file:`Documentation` with at least an entry point reStrutured Text file called |
There was a problem hiding this comment.
"with an entry point rest file" sounds strange. Had to read it twice to understand the meaning.
There was a problem hiding this comment.
How would you call that file?
| project title, release version and the like. | ||
| To render a complete documentation manual you need a folder called | ||
| :file:`Documentation` with at least an entry point reStrutured Text file called | ||
| :file:`Documentation\Index.rst` and a configuration file called |
There was a problem hiding this comment.
Instead "called" would prefer "named", also one line above.
| ├── README.rst | ||
| └── Documentation | ||
| ├── genindex.rst | ||
| ├── Includes.rst.txt | ||
| ├── About.rst |
There was a problem hiding this comment.
Where comes this "About.rst" from?
There was a problem hiding this comment.
Just to show that you also have normal content here
| :file:`Documentation/guides.xml` | ||
| ================================ | ||
|
|
||
| This XML file contains meta information and configuration used during rendering |
There was a problem hiding this comment.
In general I suggest to start with a full guides.xml example, so people can see what the file looks like without reading the whole chapter.
| :file:`README.rst` or :file:`README.md` | ||
| ======================================= | ||
|
|
||
| Full documentation contains both a README.rst and a Documentation/Index.rst |
There was a problem hiding this comment.
I don't like the phrase "full documentation" in this context.
So, this sentence says: Just add a README.rst and a Index.rst file and you have full documentation. That's it.
And why do I need a README.rst file?
There was a problem hiding this comment.
I also dont get all of this, so I moved it to a separate file so it can be dealt with later. I didnt change the content, see attached commit
Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com>
Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com>
|
@brotkrueml you are right. I transfered the first commit from this PR into a separate PR: #361 and already applied your suggestions from this review. After it is merged I will do the same with the next commit from this PR |
|
I made separate PRs for each commit in this PR |
All changes are related to the file Documentation/GeneralConventions/FileStructure.rst I broke it up into separate commits