Installation and Usage§

  1. Make sure you have Python installed.

  2. Install the Python package insipid-sphinx-theme, e.g. with pip:

    python3 -m pip install insipid-sphinx-theme --user
    

    If the command python3 isn’t available, you can try python instead. If you want to install the theme for all users (assuming you have the necessary rights), you can drop the --user flag. If you are using a virtual environment, you might also have to drop the --user flag. If you want to upgrade an existing installation, you can add the --upgrade flag.

  3. Edit the conf.py file (just create an empty file if it doesn’t exist yet, or use sphinx-quickstart) and add/edit the line:

    html_theme = 'insipid'
    
  4. Make sure your source files are in the same directory as your conf.py. If you don’t have any source files yet, you can start with a simple index.rst:

    My Docs
    =======
    
    Hello, world!
    

    At some point, you’ll probably want to have more than one page. You can use the toctree directive to include additional pages.

  5. Run Sphinx, e.g. by using:

    python3 -m sphinx <source-dir> <build-dir>
    

    … where <source-dir> is the directory that contains your conf.py, and <build-dir> is the place where the generated HTML files should be written to. For example, the full command could look something like this:

    python3 -m sphinx doc html-files
    

    For more options, see sphinx-build.

That should be it. But there are many options (Configuration) and customization possibilities (Customization) available.

Alternative Usage

It is convenient to install the theme as a Python package, because this way Sphinx can find it easily and you don’t have to worry about where the theme’s files are stored. However, the package installation is not strictly necessary (because the insipid theme is just a theme and not a full-blown Sphinx extension). If you don’t want to install the package, you can instead use html_theme_path to tell Sphinx where the directory containing the insipid directory is.

For example, you could include the insipid-sphinx-theme repository as a Git submodule in your own repository and point to that submodule in your conf.py:

html_theme_path = ['path-to-submodule/src/insipid_sphinx_theme']
html_theme = 'insipid'