Overview¶

How to install¶

To use this theme on any Sphinx based documentation, follow these steps:

Install the jupyter_alabaster_theme package using pip:

pip install jupyter_alabaster_theme

Edit your conf.py file:

1. Set the theme to jupyter_alabaster_theme:

html_theme = 'jupyter_alabaster_theme'

2. Add jupyter_alabaster_theme to the list of extensions:

extensions = [
   ...
   'jupyter_alabaster_theme',
]

3. At the bottom of conf.py, edit the following code block to select the desired theme to use for any local builds (such as during development):

# -- Read The Docs --------------------------------------------------------

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:
    # only import and set the theme if we're building docs locally
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
else:
    # readthedocs.org uses their theme by default, so no need to specify it
    # Do anything else needed to build documentation on RTD
    from subprocess import check_call as sh
    sh(['make', 'rest-api'], cwd=docs)

• To use sphinx_rtd_theme: no changes are needed if you are using the code block above.
• To use jupyter_alabaster_theme:

# -- Read The Docs --------------------------------------------------------

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

# Don't need to set html_theme if done earlier in conf.py
if on_rtd:
    # Do anything else needed to build documentation on RTD

Update Documentation Dependencies

To get your documentation to build, you will need to update its build dependencies. Update your environment.yml or requirements.txt to depend on jupyter_alabaster_theme to get the build working on ReadTheDocs. Note, we have not yet released a Conda package for this theme, so you will need to list it in the environment.yml file under the pip section.

Important Notes¶

• Use one toctree in your index.rst. More toctrees can be added within sections that are included in the main toctree.
• Avoid using captions in the toctree since that is not accessible to mobile navigation menus and the breadcrumbs.
• Avoid adding subsections that are on the same page as the section to the toctree. Subsections are not accessible to the mobile navigation menus and breadcrumbs. This can be avoided by limiting maxdepth for a toctree. Another option is to set the titlesonly option:

.. toctree::
    :titlesonly:

    title1
    title2

• More information about the toctree can be found at the Sphinx documentation site

Running the Docs Locally¶

• Fork the repository and clone it locally.
• cd into the Jupyter-Alabaster-Theme directory
• Consider using a virtualenv or conda environment to manage packages.
• Install the packages (from the root of the directory) with pip

pip install -r dev-requirements.txt

• cd into the docs directory
• The docs can be built with the following:

make clean && make html_theme

The docs will be built in build/html. They can be viewed by starting an HTTP server and navigating to 0.0.0.0:8000 in your web browser.

python3 -m http.server

Changing the Theme¶

Modifying CSS:

Do not change CSS directly, instead change Post CSS files. This project is using Post CSS, specifically the css-next module. Post CSS allows us to have nested CSS selectors and makes it easier to read them.

To Add a Post CSS file:

1. Create a file called foo.pcss in jupyter_alabaster_theme/statuc/pcss
2. Add @mimport foo.css to index.css.
3. In package.json add a script with a name css:foo and action "postcss jupyter_alabaster_theme/static/pcss/foo.pcss -o jupyter_alabaster_theme/static/css/foo.css",

Installing Post CSS and other npm dependencies

npm install

To compile Post CSS into CSS:

npm run css

Modifying Sphinx templates:

1. Make appropriate changes to templates.
2. Uninstall jupyter_alabaster_theme:

pip uninstall jupyter_alabaster_theme

3. Install the package:

pip install .

4. Re-build the Sphinx documentation (from the appropriate directory) and refresh your browser.

make clean && make html