This repository aims at centralizing the artifacts related to the full documentation of the Bao Project. The documents are fully written in American English, following the reStructureText (reST) format, and hosted in the ReadTheDocs web service. We also use the Sphinx tool to generate the documentation in the html format.
The bao-docs repository follows the basic directory layout defined by Sphinx , with two top-level directories:
build: contains the resulting rendered documentation after running the Sphinx buildsource: holds each reST document following the structure as explained below
The organization of documentation under the source directory is structured
into 4 top-level folders. The following table specifies the meaning of each
folder:
| Folder | Description |
|---|---|
| introduction | Holds all documentation that is supposed to be the first contact to the project, presenting an overview of the project and a *getting started* guide to help new users. |
| user_manual | Holds all documentation that intend to assist users during the utilization of the Bao framework. |
| internals | |
| development |
Holds all documentation that specifies the guidelines to take into consideration during the development activities, namely, coding and documentation style, contributing workflow, the CI pipeline, testing framework, among others. |
To generate the documentation locally, developers need to install a set of prerequisites, depending on the host machine. Follow the steps described below for your specific machine.
For Linux users, start by installing dependencies and each tool package and extension (i.e., Sphinx, the spell checker extension sphinxcontrib.spelling, the sphinx tabs extension and the format checker doc8).
sudo apt-get install enchant
pip install sphinx sphinxcontrib-spelling sphinx-tabs pyenchant doc8 sphinx-rtd-themeIf you wish to contribute to the documentation you should first take a close look at the contribution and follow the documentation guidelines. The documentation sources' spelling and formatting are automatically verified with the help of the bao CI documentation checkers.
For Linux users, start by checking the documentation for spell and format errors. To check for spelling typos, you need to run the following command:
make spellingTo check for format issues, you need to run the following command:
make rst-formatAfter correcting all outputted errors, you can build the documentation and generate the html files:
make htmlThe html files are under the build folder and you can visualize them by
opening the html/index.html file on your browser.