From a producer's point of view, each document is processed exactly like a Python module. It should be stored in the version control system and work like code. Writers do not care about the final appearance of their prose and where it is available; they just want to make sure that they are writing a document that is the single source of truth on the topic covered. reStructuredText files stored in a folder tree are available in the version control system, together with the software code, and are a convenient solution to build the documentation landscape for producers.
By convention, the docs folder is used as a root of documentation tree, as follows:
$ cd my-project $ find docs docs docs/source docs/source/design docs/source/operations docs/source/usage docs/source/usage/cookbook docs/source/usage/modules docs/source/usage/tutorial
Notice that the tree is located in a source folder because the docs folder will be used as a root folder to set up a special tool in the next section.
From there, an index.txt file can be added at each level (besides the root), explaining what kind of documents the folder contains, or summarizing what each subfolder contains. These index files can define a listing of the documents they contain. For instance, the operations folder can contain a list of operations documents that are available, as follows:
========== Operations ========== This section contains operations documents: − How to install and run the project − How to install and manage a database for the project
It is important to know that people tend to forget to update such lists of documents and tables of contents. So, it is better to have them updated automatically.
In the next section, we will discuss one tool that, among many other features, can also handle this use case.