-
-

Quick start

-

Nefertiti for Sphinx can be setup and running in a blink of an eye. Follow this quick start guide to go through the minimal steps to use it with your project.

-
-

Note

-

This page assumes that you want to try Nefertiti on an already existing Sphinx project.

-
- -
-

Customize the theme

-

The following details of Nefertiti for Sphinx can be customized:

-
-
    -

  1. Fonts.

    2. -

  2. Color set: blue, indigo, purple, pink, red, …

    3. -

  3. Pygments styles for light and dark color schemes.

    4. -

  4. Repository name and URL to display it in the header.

    5. -

  5. Project version dropdown selector.

    6. -

  6. Footer links.

    7. -
-
-

They all are entries of the html_theme_options setting of your conf.py file.

-
-

1. Fonts

-

There are 5 options related to font face customization and 2 options related to font size.

-

The font face options are:

-
-
    -

  • sans_serif_font: Default site font, defaults to Nunito.

    • -

  • monospace_font: Default monospace font, for code blocks, defaults to Red Hat Mono.

    • -

  • project_name_font: The font for the Project’s name. sans_serif_font otherwise.

    • -

  • documentation_font: reStructuredText and Markdown content. sans_serif_font otherwise.

    • -

  • doc_headers_font: To render documentation headers. documentation_font otherwise.

    • -
-
-

And the font size options:

-
-
    -

  • monospace_font_size: The CSS font-size for the monospace_font. ie: "1rem".

    • -

  • documentation_font_size: The CSS font-size for the documentation_font. ie: "1.1rem".

    • -
-
-

Edit your conf.py file and add or modify your html_theme_options setting with the following content. By the way, the fonts referred to in this example are part of the Nefertiti for Sphinx distribution. If you want to use other Open Source licensed fonts read the section “How to add more fonts” to include them with your project.

- 
html_theme_options = {
-    "sans_serif_font": "Mulish",
-    "monospace_font": "Ubuntu Mono",
-    "monospace_font_size": "1.1rem",
-    "project_name_font": "Montserrat",
-    "documentation_font": "Assistant",
-    "documentation_font_size": "1.1rem",
-    "doc_headers_font": "Georgia",
-}
-
-
-

Save the content, clean up the build directory, build it and serve it again:

- 
$ make clean
-    $ make html
-    $ python -m http.server -d build/html
-
-
-

Visit http://localhost:8000 to take a look at the changes.

-
-
-

2. Color sets

-

Another customizable feature of the theme is the color set. In the header of this documentation you can see a dropdown with a palette icon. The colors listed in the dropdown represent the available color sets. Try them to apply the selected color set to this documentation.

-

To customize the color set in your project add an entry style to the html_theme_options setting in your conf.py module:

- 
html_theme_options = {
-    # ... other options ...
-    "style": "pink",
-}
-
-
-

When style is not given the theme defaults to cyan.

-
-
-

3. Pygments styles

-

Pygments is the package in charge of rendering code blocks. Sphinx supports two settings related with pygments:

-
-
    -

  • pygments_style, applied when browser’s prefers-color-scheme returns light.

    • -

  • pygments_dark_style, applied when browser’s prefers-color-scheme returns dark.

    • -
-
-

Nefertiti for Sphinx extends the use of these settings in a way that their styling is applied when the user selects the scheme in the light/dark dropdown, at the right side of the header.

-

If your Sphinx project has code-blocks, try changing the pygments style settings and see how they are applied when switching between light and dark schemes in the header. Update your conf.py module:

- 
html_theme_options = {
-    # ... other options ...
-    "pygments_style": "solarized-light",
-    "pygments_dark_style": "solarized-dark",
-}
-
-
-

Then clean up and rebuild the project, as usual.

-

See more code blocks rendered with Pygments in the Code blocks document in Nefertiti User’s guide.

-
-
-

4. Repository data

-

If your Sphinx project is about a source code product, and it resides in a Git repository, in GitHub or GitLab, Nefertiti can display information relative to your repository in the header.

-

Just add the repository_name and repository_url keys to your html_theme_options setting:

- 
html_theme_options = {
-    # ... other options ...
-    "repository_name": "danirus/sphinx-nefertiti",
-    "repository_url": "https://github.com/danirus/sphinx-nefertiti",
-}
-
-
-

Clean up and rebuild the project, as usual.

-
-
-

5. Version dropdown

-

If your project is available in different versions Nefertiti for Sphinx can display a dropdown in the header to switch between them. If you use readthedocs it is enabled by default so long as you have enabled different versions in the admin interface of readthedocs.

-

If you host different versions in different URLs, like:

- - - - - - - - - - - - - - - - - -

Version

URL

v2.9.9

https://django-comments-xtd.readthedocs.io/en/latest/

v2.8.5

https://django-comments-xtd.readthedocs.io/en/2.8.5/

v2.7.2

https://django-comments-xtd.readthedocs.io/en/2.7.2/

-

Enable the version dropdown by adding the versions key to your html_theme_options setting:

- 
html_theme_options = {
-    # ... other options ...
-    "versions": [
-        ("v2.9.9", "https://django-comments-xtd.readthedocs.io/en/latest/"),
-        ("v2.8.5", "https://django-comments-xtd.readthedocs.io/en/2.8.5/"),
-        ("v2.7.2", "https://django-comments-xtd.readthedocs.io/en/2.7.2/"),
-    ]
-}
-
-
-

Clean up and rebuild the project, as usual.

-
- -
-
-