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 details)

Uploaded Source

Built Distribution

sphinx_documatt_theme-0.0.1-py3-none-any.whl (103.2 kB view details)

Uploaded Python 3

File details

Details for the file sphinx_documatt_theme-0.0.1.tar.gz.

File metadata

  • Download URL: sphinx_documatt_theme-0.0.1.tar.gz
  • Upload date:
  • Size: 104.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.6.9

File hashes

Hashes for sphinx_documatt_theme-0.0.1.tar.gz
Algorithm Hash digest
SHA256 61a2a17f731fe9627d6a125e8e022a3aeaaebefabfcbab6054ac6136380e7845
MD5 3746d01110991788a013b15366ef1dd1
BLAKE2b-256 94f70d1508edd9d9021a41d8328ed8ab3dbc3590bba4bd9d9985c2b1358ccb78

See more details on using hashes here.

File details

Details for the file sphinx_documatt_theme-0.0.1-py3-none-any.whl.

File metadata

  • Download URL: sphinx_documatt_theme-0.0.1-py3-none-any.whl
  • Upload date:
  • Size: 103.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.6.9

File hashes

Hashes for sphinx_documatt_theme-0.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 937e04be04db5ee53df08b82af4f0cafe0613302805eade164005a7ca5943f4b
MD5 a932bf1ad7c703df4875933cbd888b96
BLAKE2b-256 676d9806c2cca360aa36d431483ee306eb3d603e23374c951e8c4818d28bc667

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page