Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

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.

Files for sphinx-documatt-theme, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size sphinx_documatt_theme-0.0.2-py3-none-any.whl (103.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size sphinx_documatt_theme-0.0.2.tar.gz (104.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page