Skip to main content

Documatt Theme for Sphinx documentation projects

Project description

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.

https://gitlab.com/documatt/sphinx-themes/-/raw/master/sphinx_documatt_theme/screenshot.png?inline=false

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_documatt_theme-0.0.1.tar.gz (104.3 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page