Documentation Workflow

This page lists my personal workflow for incorporating Sphinx into my documentation.

Reference Workflow

In order to maintain an organized structure of reference material for all of the software engineering concepts I encounter on a daily basis, I’ve decided to implement reference repositories to separate all of the information into modules. Below are the steps that I implement to support consistency.

1. Create new repository on GitHub labelled ‘ref-<name>’

2. Clone repo to PC

3. Copy .gitignore file into base of directory

4. Within the repo, execute sphinx quick-start

5. Install sphinx-rtd-theme into the directory following their instructions.

6. Create and .rst files and add them to index.rst

7. Commit and push to GitHub

8. In the master repository, add the new repository as a submodule using the following command in docs/:

   git submodule add <repo> [<path>]
   

9. If cloning the master repo with submodules, execute the following command:

   git submodule init
   

10. If needing to update all the submodules in the master repository, execute the following command:

    git submodule update --recursive --remote
    

11. Add the submodule index to the master index.rst

12. Ensure that the webhook for ReadTheDocs on the master repo is correctly set up

13. Commit and push master repo updates to GitHub, and the changes should be reflected on ReadTheDocs

Note

Any git submodules must use HTTPS rather than SSH to be properly interpreted by ReadTheDocs