3. Sphinx

Sphinx is a documentation generator. This means that it takes source files in plain text, and generates html files. In our case, it takes plain text files in reStructuredText format, and outputs html.

3.1. Installations

Sphinx and some useful extensions can be installed individually or via a requirements.txt file.

For installing all in one go via a requirements.txt file steps: Install python packages via requirements.txt.

See https://pypi.org/project/Sphinx/

3.2. Suggested Sphinx extensions

Sphinx and the following suggested extensions can be installed individually or via the requirements.txt file.

For sphinx-rtd-theme go to: https://pypi.org/project/sphinx-rtd-theme/
For sphinx-copybutton go to: https://pypi.org/project/sphinx-copybutton/
For sphinx-copybutton css go to: https://github.com/executablebooks/sphinx-copybutton/blob/master/sphinx_copybutton/_static/copybutton.css
For sphinx-togglebutton go to: https://pypi.org/project/sphinx-togglebutton/
For sphinx-design go to: https://pypi.org/project/sphinx_design/
For sphinx-new-tab-link go to: https://pypi.org/project/sphinx-new-tab-link/

3.3. Dependencies

For latest updates and dependencies see: https://sphinx-rtd-theme.readthedocs.io/en/stable/changelog.html

pip install Sphinx
pip install sphinx-copybutton
pip install sphinx-rtd-theme
pip install sphinx-togglebutton
pip install sphinx_design
pip install sphinx-new-tab-link

To force upgrade to the latest compatible versions of all packages:

pip install --upgrade Sphinx
pip install --upgrade sphinx-copybutton
pip install --upgrade sphinx-rtd-theme
pip install --upgrade sphinx-togglebutton
pip install --upgrade sphinx_design
pip install --upgrade sphinx-new-tab-link

See the python section for using a requirements.txt file then using:

pip install -r requirements.txt

To force upgrade to the latest compatible versions of all packages:

pip install -U -r requirements.txt

3.4. All pip installed versions

Check the installed version of all pip installed packages with:

pip list

Check the installed version of sphinx and recommended extensions individually with:

pip show Sphinx
pip show sphinx-copybutton
pip show sphinx-rtd-theme
pip show sphinx-togglebutton
pip show sphinx_design
pip show sphinx-new-tab-link

Check the installed version of sphinx and recommended extensions with a single command and filter for name and version with:

pip show Sphinx, sphinx-copybutton, sphinx-rtd-theme, sphinx-togglebutton, sphinx_design, sphinx-new-tab-link |
Select-String "Name|Version"

Name: Sphinx

Version: 9.1.0

Name: sphinx-copybutton

Version: 0.5.2

Name: sphinx_rtd_theme

Version: 3.1.0

Name: sphinx-togglebutton

Version: 0.4.4

Name: sphinx_design

Version: 0.7.0

Name: sphinx-new-tab-link

Version: 0.8.1

3.5. Install Sphinx

Press Win + X + C to open the Command prompt.
Install the Sphinx library.

pip install sphinx

Install the Sphinx library using a specific version..

pip install sphinx==9.1.0

To upgrade include the -U flag.

pip install -U sphinx

Check the installed version with:

sphinx-build --version

3.6. Install the Sphinx theme for Read the Docs

The sphinx_rtd_theme is used by other RTD guides, so it is best to use for consistency of look and feel.
To use sphinx_rtd_theme, make the changes to the conf.py file that are detailed at VSCode conf.py file.
Install the Sphinx theme for read the docs.

pip install sphinx_rtd_theme

To upgrade include the -U flag.

pip install -U sphinx_rtd_theme

Check the installed version with:

pip show sphinx-rtd-theme

3.7. Install the sphinx-copybutton Extension

The sphinx-copybutton Extension adds a copy button to code blocks.
To use sphinx-copybutton, make the changes to the conf.py file that are detailed at VSCode conf.py file.
Install the Sphinx Extension: sphinx-copybutton:

pip install sphinx-copybutton

To upgrade include the -U flag:

pip install -U sphinx-copybutton

Check the installed version with:

pip show sphinx-copybutton

3.8. Install the sphinx-togglebutton Extension

The sphinx-togglebutton Extension adds the ability to Collapse Sphinx admonitions (notes, warnings, etc) so that their content is hidden until users click a toggle button.
- To use sphinx-togglebutton, make the changes to the conf.py file that are detailed at VSCode conf.py file.
Install the Sphinx Extension: sphinx-togglebutton:

pip install sphinx-togglebutton

To upgrade include the -U flag:

pip install -U sphinx-togglebutton

Check the installed version with:

pip show sphinx-togglebutton

3.9. Install the sphinx_design Extension

The sphinx_design Extension adds drop downs and tabs.
To use sphinx_design, make the changes to the conf.py file that are detailed at VSCode conf.py file.
Install the Sphinx Extension: sphinx_design:

pip install sphinx_design

To upgrade include the -U flag:

pip install -U sphinx_design

Check the installed version with:

pip show sphinx_design

3.10. Install the sphinx_new_tab_link Extension

The sphinx_new_tab_link Extension opens links in a new tab.
To use sphinx_new_tab_link, make the changes to the conf.py file that are detailed at VSCode conf.py file.

pip install sphinx_new_tab_link

To upgrade include the -U flag:

pip install -U sphinx_new_tab_link

Check the installed version with:

pip show sphinx-new-tab-link