Welcome to Agent666’s Sphinx RTD Theme Template

Documentation Status

Changes from the standard Sphinx theme

  1. Added Sphinx RTD Theme
  2. Added a number of useful built in Sphinx extensions
    1. intersphinx
    2. autodoc
    3. mathjax
    4. viewcode
    5. todo
    6. githubpages
    7. napoleon - Allows parses NumPy and Google style docstrings
  3. Added reference to use Pygments code syntax highlighter (note if you want to modify this theme copy the pygments.css file into ../docs/source/html/_static/css directory and change any of the values and it will overwrite the default Pygment highlighting theme options)
  4. Added reference to an additional theme (Cloud Sphinx Theme) that provides for better table formatting options (delete the reference to the extension in the Sphinx config file (conf.py) if you do not want to install/use this)
  5. Sets a number of default html theme options, such as showing the version in the title, adding next/previous buttons top and bottom, etc
  6. Changed default code block and inline code fonts to Inconsolata and bumped up font size from 12px to 14px for a clearer/crisper layout via a custom layout.html file and custom.css file, added word-wrap in code blocks
  7. Changed default description fonts to Inconsolata and bumped up font size from 14px to 16px for a clearer layout, via custom layout.html file and custom.css file. Where the font size for the descriptions now more closely match the other default font sizes used for the typical body text (its much smaller by default)
  8. Changed default max page width from 800px to 1200px max to better suit displaying both more text and longer code lines via custom custom.css file (suits 150 characters per line which is my default goto style). This is based on the following code style:-
Black Code

Black Code style modified to use max 150 characters per line and prefered single quotes using the following settings:-

Visual Studio Code settings (settings.json)
"python.formatting.provider": "black",
"python.formatting.blackArgs": [
   "--line-length=150",
   "--skip-string-normalization",
],

Resulting visual changes

_images/Comparison.png

To Use

  • Copy the docs folder to your repository
  • Modify conf.py line sys.path.insert(0, os.path.abspath('../../')) to the path(s) where modules are stored that you want to be processed on the basis of docstrings within the modules themselves
  • Run make html at the command prompt from within the ../docs directory to build html files
  • View the built html files within the _build directory
  • Note if you subsequently modify the custom.css file then you may need to run make clean followed by make html to pickup the css changes
  • Review demo files under _demo directory for examples of formatting, etc. This directory can be removed, and references to it removed from index.rst file. Note the example content is taken from the official RTD pages, and due to the wider default page width, and the use of the Sphinx RTD Theme some of the formatting may look different (for example footnotes, and some of the examples of test wrapping around images). Some of the intentional errors have been removed so the documents build remotely on https://sphinx-rtd-theme-template.readthedocs.io/en/latest/

Prerequisites

Support

If you require support or have any feature requests related to the Sphinx RTD Theme Template package please feel free to raise an issue on Github.

For some further information and tips on setting up the theme you can refer to this blog post:- https://engineervsheep.com/2019/parabola-8/