PC-Using-RTD

These docs provide a simple instruction list for setting up automatic updating of your project documentation hosted at ReadTheDocs.

Overall Process

Python -> Sphinx -> VSCode -> reStructuredText -> GitHub -> ReadTheDocs

1. Using Python, set up Sphinx to translate the .rst files into HTML (and PDF) file formats.

2. In VSCode, create plain text source files in reStructuredText (.rst) format.

3. In VSCode, push the documentation changes to a GitHub repository.

4. Set up ReadTheDocs to automatically update via a webhook to GitHub.

📚 Table of Contents:

• 1. Introduction
  • 1.1. Required software
• 2. Python
  • 2.1. Install Python
  • 2.2. Create a python Virtual environment
  • 2.3. Using the python Virtual environment in VSCode
  • 2.4. Update pip
  • 2.5. Install python packages via requirements.txt
  • 2.6. Updating python packages in a requirements file
  • 2.7. Save package list to requirements file
  • 2.8. Updating python packages
  • 2.9. Uninstalling all python packages
• 3. Sphinx
  • 3.1. Installations
  • 3.2. Suggested Sphinx extensions
  • 3.3. Dependencies
  • 3.4. All pip installed versions
  • 3.5. Install Sphinx
  • 3.6. Install the Sphinx theme for Read the Docs
  • 3.7. Install the sphinx-copybutton Extension
  • 3.8. Install the sphinx-togglebutton Extension
  • 3.9. Install the sphinx_design Extension
• 4. Jupyter
  • 4.1. Jupyter-sphinx
    • 4.1.1. Install the jupyter-sphinx extension
    • 4.1.2. docs/requirements.txt
    • 4.1.3. VSCode conf.py file
    • 4.1.4. Usage
  • 4.2. sphinx-thebe
    • 4.2.1. Install the sphinx-thebe extension
    • 4.2.2. docs/requirements.txt
    • 4.2.3. VSCode conf.py file
    • 4.2.4. Usage
    • 4.2.5. class: thebe
  • 4.3. nbsphinx
    • 4.3.1. Install the nbsphinx extension
    • 4.3.2. VSCode Jupyter extension
    • 4.3.3. docs/requirements.txt
    • 4.3.4. VSCode conf.py file
    • 4.3.5. Usage
  • 4.4. sphinxcontrib-jupyter
    • 4.4.1. Install the sphinxcontrib-jupyter extension
    • 4.4.2. VSCode conf.py file
    • 4.4.3. Usage
• 5. VSCode
  • 5.1. Install VSCode
  • 5.2. Install VSCode reStructuredText extension
  • 5.3. Install VSCode reStructuredText Syntax highlighting extension
• 6. VSCode Project Folder and Sphinx
  • 6.1. Create docs folder
  • 6.2. Sphinx-quickstart
• 7. VSCode reStructuredText
  • 7.1. Usage
  • 7.2. index.rst
  • 7.3. Documentation as .rst files
  • 7.4. Images
  • 7.5. Sample code
• 8. VSCode make html and pdf
  • 8.1. View docs as html
  • 8.2. View docs as html in VSCode
  • 8.3. View docs as html
  • 8.4. View docs as html using localhost
  • 8.5. View docs as pdf
  • 8.6. Make latex
• 9. VSCode special files
  • 9.1. Add files
  • 9.2. docs/requirements.txt
  • 9.3. docs/.readthedocs.yaml
  • 9.4. docs/.gitignore
  • 9.5. .gitignore
  • 9.6. breadcrumbs.html
  • 9.7. Custom css
  • 9.8. Custom logos
• 10. VSCode conf.py file
  • 10.1. sphinx_rtd_theme
  • 10.2. sphinx-rtd-theme Theme Options
  • 10.3. Custom css
  • 10.4. Custom logo
• 11. Git
  • 11.1. Install Git
  • 11.2. Check installed version of Git
  • 11.3. Set Git Name & Email
  • 11.4. Git in VSCode
  • 11.5. Git in PyCharm
• 12. GitHub and VSCode
  • 12.1. GitHub account
  • 12.2. VSCode starting from creating a new empty repository
  • 12.3. GitHub settings
  • 12.4. Initialize GitHub in VSCode
  • 12.5. Initialize GitHub in VSCode starting from an existing repository
  • 12.6. VSCode GitHub updates
  • 12.7. VSCode GitHub controls
  • 12.8. VSCode Git staging and commits
    • 12.8.1. Changes and Staged Changes
    • 12.8.2. Commits
  • 12.9. VSCode starting from Cloning a repository
• 13. Read the docs (RTD)
  • 13.1. Sign up to RTD
  • 13.2. Connect to GitHub
  • 13.3. Import GitHub project
  • 13.4. Integrations - GitHub Webhooks
  • 13.5. RTD Advanced Settings
  • 13.6. RTD Documentation
• 14. Push VSCode changes to GitHub
  • 14.1. GitHub

---

An alternate approach can be followed in the techwritingmatters tutorial which has 4 youtube videos. https://techwritingmatters.com/documenting-with-sphinx-tutorial-intro-overview#Structure_of_the_Tutorial It starts by cloning a new GitHub repository to the computer. It is Mac based. It uses a text editor instead of VSCode.

The above steps are suitable for one author using the master branch only. For collaboration and the use of feature branches for development see the command line interface (CLI) commands details below:

More on Git:

• 1. Git CLI
  • 1.1. Git Help
  • 1.2. 2 scenarios:
• 2. Existing project on local machine
  • 2.1. Initialize the repository on local machine
  • 2.2. Ignore files
  • 2.3. Working tree -> Staging Area -> History
  • 2.4. Add files to Staging Area
  • 2.5. Git Status
  • 2.6. Remove files from Staging Area
  • 2.7. Commit files from Staging Area
  • 2.8. View Commit history
  • 2.9. Rename branch
• 3. Clone remote project to work on
  • 3.1. Clone a git repository
  • 3.2. View information about remote repository
  • 3.3. View changes made
  • 3.4. Commit changes to files
  • 3.5. Pull and Push commit to remote repo
  • 3.6. Create branch for desired feature to work in
  • 3.7. Merge a branch
  • 3.8. Delete a branch after merging it
  • 3.9. Remove file from commit not yet pushed
  • 3.10. Change commit message not yet pushed
  • 3.11. Add a file created since last commit but not yet pushed
  • 3.12. Move commit from master to feature branch not yet pushed
  • 3.13. Soft reset
  • 3.14. Default reset
  • 3.15. Hard reset
  • 3.16. Recover from Hard reset
  • 3.17. Make changes when changes have been pushed
  • 3.18. Git Stash
  • 3.19. Git Stash from master to feature branch
  • 3.20. Remove the git tracking (delete hidden .git folder)