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.

3.2. Suggested Sphinx extensions

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

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 in powershell with:

pip show sphinx sphinx-copybutton sphinx-rtd-theme sphinx-togglebutton sphinx_design sphinx-new-tab-link |
Select-String "^Name:|^Version:" |
ForEach-Object { $_.Line -replace '^Name:\s*', '' -replace '^Version:\s*', ': ' } |
Group-Object -Property { [math]::Floor(($global:i++) / 2) } |
ForEach-Object { $_.Group -join "" }
Sphinx: 9.1.0
sphinx-copybutton: 0.5.2
sphinx_rtd_theme: 3.1.0
sphinx-togglebutton: 0.4.5
sphinx_design: 0.7.0
sphinx-new-tab-link: 0.8.1

3.5. Check latest versions available

  • Check the latest version of all pip packages with this powershell script:

"sphinx", "sphinx-copybutton", "sphinx-rtd-theme", "sphinx-togglebutton", "sphinx_design", "sphinx-new-tab-link" | ForEach-Object {
    $indexLine = pip index versions $_ | Select-Object -First 1
    if ($indexLine -match '\(([\d\.]+)\)') {
        Write-Host ("{0,-25} : {1}" -f $_, $matches[1]) -ForegroundColor Cyan
    }
}

  • Check the latest version of all pip packages using the requirements.txt file with this powershell script:

Get-Content .\requirements.txt | ForEach-Object {
    # Clean up the line: strip spaces and ignore comments or empty lines
    $line = $_.Trim()
    if ($line -and -not $line.StartsWith("#")) {

        # Extract just the package name before any ==, >=, <=, or [extras]
        $pkg = ($line -split '[<>=~\[]')[0].Trim()

        # Query pip index for the latest version line
        $indexLine = pip index versions $pkg | Select-Object -First 1

        # Extract the version number inside the parentheses
        if ($indexLine -match '\(([\d\.]+)\)') {
            Write-Host ("{0,-25} : {1}" -f $pkg, $matches[1]) -ForegroundColor Cyan
        } else {
            Write-Host ("{0,-25} : Could not find version" -f $pkg) -ForegroundColor Yellow
        }
    }
}

3.6. 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.7. 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.8. 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.9. 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.10. 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