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
Using Python, set up Sphinx to translate the .rst files into HTML (and PDF) file formats.
In VSCode, create plain text source files in reStructuredText (.rst) format.
In VSCode, push the documentation changes to a GitHub repository.
Set up ReadTheDocs to automatically update via a webhook to GitHub.
📚 Table of Contents:
- 1. Introduction
- 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
- 5. VSCode
- 6. VSCode Project Folder and Sphinx
- 7. VSCode reStructuredText
- 8. VSCode make html and pdf
- 9. VSCode special files
- 10. VSCode conf.py file
- 11. Git
- 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.9. VSCode starting from Cloning a repository
- 13. Read the docs (RTD)
- 14. Push VSCode changes to 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
- 2. Existing project on local machine
- 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)