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?¶

Fork and clone the PiCar Github repository
Navigate to the ../readthedocs directory:
```
cd PiCar/docs/readthedocs
```

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
  changelogs.rst
  contributors.rst

It is recommended to use a comprehensive text editor like Atom or Sublime text. Atom can be installed by:
```
sudo add-apt-repository ppa:webupd8team/atom
sudo apt-get update
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.

After making a change in an .rst , go back to ../readthedocs and enter the command to build the html pages:
```
make html
```
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.

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.

Warning

You have to run make html and check the HTML output before pushing your changes, otherwise the expected HTML changes will not be rendered.

Note

If you want to create readthedocs style documentation for an entirely new repository, or you want to test and see how the HTML pages looks online, you will need to create a readthedocs account (either import your GitHub account or create a new one), and import that specific repository. This ensures that when new commits are submitted, the docs are updated automatically as well.

Resources¶

Rest and Sphinx Memo