Read the Docs Basics

What is Read the Docs?

Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you. We use it to keep the PiCar documentation organized and updated. If you make a significant change to the PiCar repository or project, you are recommended to update the Read the Docs documentation for PiCar. It uses reStructuredText file format to build the HTML files using Sphinx.

How to update the Docs?

1. Fork and clone the PiCar Github repository
2. Navigate to the ../readthedocs directory:

cd PiCar/docs/readthedocs

3. The documentation is currently ordered as the following:

index.rst
conf.py
chapters/
  introduction.rst
  tutorials.rst
  usage.rst
  tutorials/
    raspberry_pi_tutorial.rst
    arduino_tutorial.rst
    github_tutorial.rst
    linux_tutorial.rst
    readthedocs_tutorial.rst
  usage/
    mechanical
    electronics
    software
  contributors.rst

4. It is recommended to use a comprehensive text editor like Atom or Sublime text. Atom can be installed by:

sudo apt-get install atom

Atom can be launched in the ../readthedocs directory by:

atom .

Note

For more information on the different commands available for .rst type files, check out the Rest and Sphinx memo.

5. After making a change in an .rst , go back to ../readthedocs and enter the command to build the html pages:

make html

6. To preview the changes, navigate to ../readthedocs/_build/html and open index.html in a browser.

Note

The PiCar Read the Docs is using the sphinx_rtd_theme theme. This can be change in the ../readthedocs/conf.y file. The version number, project name, authors, language support can be changed here too.

Warning

ReadtheDocs is very strict with indentation and formating. Check warning messages (with the associated line number) to fix issues.

7. Once you have made changes without errors and warnings and are satisfied with the updated documentation, submit a pull request to the latest Github branch.