sphinx-documatt-theme 0.0.1

Documatt Theme for Sphinx documentation projects

Mobile friendly Sphinx theme designed to provide great documentation reading experience with beautiful typography.

This theme is default theme of Documatt’s Techwriter at work blog but you are welcome to use it with any Sphinx project.

Installation

Install (on the commandline):

$ pip install sphinx-documatt-theme

Use it (in your conf.py):

html_theme = "sphinx_documatt_theme"

Configuration

Theme as only option - set “motto” displayed by default in the cover (block bellow breadcrumb near header), and in the footer. Set your very own motto:

html_theme_options = {
    "motto": "Write and read beautiful books and documentation in easy way with our powerful writing platform."
}

Customization

To customize the theme, create _templates/layout.html in your Sphinx project root. layout.html is the most important template to override. Start the file with the extends:

{% extends "!layout.html" %}

Now you can override (customize) so-called blocks, i.e. parts of page. The most important blocks are:

• mastercover a cover (sometimes called a hero) used for master page (usually index.rst). Cover is shown bellow breadcrumb navigation.

• nonmastercover a cover used for non-master pages (usually anything except index.rst). Both cover block shows motto by default.

• coverrightcolumn right column next to the cover is useful for example for social buttons.

• rightsidebar right column next to the main document body. Again, typically used to place share buttons.

• extrafooter block right before trailing </body>. By default is empty, but it’s ideal place to put e.g. your website analytics HTML code or cookie bar.

The complete example may look:

{% extends "!layout.html" %}

{% block mastercover %}
    <h1 class="title is-2 has-text-primary">
        Techwriter at work <span class="has-text-weight-light">blog</span>.
    </h1>
    <h2 class="subtitle is-4">
        Living and writing documentation at Documatt, small team of programmers
        that <span class="has-text-primary">do write</span> documentation too.
    </h2>
{% endblock %}

{% block coverrightcolumn %}
    <a href="https://twitter.com/documattcom?ref_src=twsrc%5Etfw"
       class="twitter-follow-button" data-show-count="false">Follow us</a>
    <script async src="https://platform.twitter.com/widgets.js"
            charset="utf-8"></script>
{% endblock %}

{% block extrafooter %}
    <script type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js?theme=grey&tracking=1&thirdparty=1&always=1&hideDetailsBtn=1&showPolicyLink=1&privacyPage=https%3A%2F%2Fdocumatt.com%2Fabout%2Flegal%2Fprivacy%2F"></script>
{% endblock %}

Open theme’s layout.html to see all blocks you can override.