Skip to main content

Sphinx theme for Xanadu open-source Python packages

Project description

Xanadu Sphinx Theme

The Xanadu Sphinx Theme (XST) is a Sphinx theme used for open-source Xanadu software projects.

A fork of the Guzzle Sphinx theme, the theme has the following features:

  • Responsive. Fluid layout that automatically adjusts for phone, tablet, and computer screens.

  • LaTeX Macros. Comes with built-in support for MathJAX and common predefined quantum optics LaTeX macros.

  • Cohesive Design. Unifies the appearance of all Xanadu Sphinx documentation.

Installation

The Xanadu Sphinx Theme requires Python 3.7 or later. The latest version of the XST can be installed directly from the GitHub repository using pip:

pip install xanadu-sphinx-theme

Getting Started

Once installed, simply add or modify the following variables of your Sphinx conf.py configuration file to start using the Xanadu Sphinx Theme:

from xanadu_sphinx_theme import templates_dir

# Add Xanadu Sphinx Theme autosummary templates
templates_path = [templates_dir()]

html_theme = "xanadu"

html_theme_options = {
    "navbar_name": "Example Project",
    "navbar_logo_colour": "#123456",

    "navbar_home_link": "https://example.com",

    "github_repo": "",
    "navbar_left_links": [
        {
            "name": "Tutorials",
            "href": "https://example.com/tutorials",
            "img": "_static/tutorial.png",
            "img_width": "30px",
        },
        {
            "name": "Install",
            "href": "install.html",
        },
        {
            "name": "Documentation",
            "href": "index.html",
            "active": True,
        }
    ],

    "navbar_right_links": [
        {
            "name": "FAQ",
            "href": "https://example.com/faq.html",
            "icon": "fas fa-question",
        },
        {
            "name": "GitHub",
            "href": "https://github.com/XanaduAI/example",
            "icon": "fab fa-github",
        }
    ],

    "extra_copyrights": [
        "TensorFlow, the TensorFlow logo, and any related marks are "
        "trademarks of Google Inc."
    ],

    "google_analytics_tracking_id": "UA-116279123-2",

    "prev_next_button_colour": "#b13a59",
    "prev_next_button_hover_colour": "#712b3d",
    "toc_marker_colour": "#b13a59",
    "table_header_background_colour": "#ffdce5",
    "border_colour": "#b13a59",
    "text_accent_colour": "#b13a59",
}

Configuration

The Xanadu Sphinx Theme supports the following options. These should be added to the html_theme_options dictionary in your conf.py file.

google_analytics_tracking_id

Google Analytics tracking ID to enable website analytics.

github_repo

The GitHub organization and repository associated with the documentation. E.g., for a GitHub repository https://github.com/Organization/repo, this should be "github_repo": "Organization/repo".

Table of contents

The following options customize the table of contents.

toc_overview

If True, the project name, and a link to the homepage index.rst, is included in the left-hand table of contents.

toc_global

Whether to show the global table of contents by default via the left sidebar. If False, then the left sidebar will be disabled.

toc_subset

If set to True, and the current page has no local table of contents, the right-hand table of contents will instead display the current subset of the document tree. That is, the right-hand ToC will display the location in the document of the current page. If False, and the current page has no local table of contents, no right-hand ToC will be shown.

relations

If True, then Next and Previous buttons are included at the bottom of every page, allowing navigation according to the table of contents.

Style Colours

The following options allow the colours of various theme elements to be altered. These should be fully qualified CSS color specifiers such as #004B6B or #444.

border_colour

Border colour of accent rules and table headers.

code_colour

Colour of code blocks and teletype text. Defaults to #8D1A38.

prev_next_button_colour and prev_next_button_hover_colour

Colours of the “Next” and “Previous” navigation buttons located at the bottom of most pages.

social_icon_colour

Colour of the social icons.

table_header_background_colour

Background colour of table headers.

text_accent_colour

Accent colour for text such as download links.

toc_marker_colour

Colour of the marker beside the current ToC entry.

toc_mobile_heading_colour and toc_mobile_heading_background_colour

Text and background colours of the mobile ToC heading.

Directives

The Xanadu Sphinx Theme implements the custom Sphinx directives listed below. For more information, consult the relevant Python module in the directives package.

Community Card

<No example is available yet.>

Details

.. details::
    :title: Usage Details

    In general, the block takes :math:`D` parameters and **must** have the following signature:

    .. code-block:: python

        unitary(parameter1, parameter2, ... parameterD, wires)

    For a block with multiple parameters, ``n_params_block`` is equal to the number of parameters in ``block``.
    For a block with a single parameter, ``n_params_block`` is equal to the length of the parameter array.
Details

Index Card

.. index-card::
    :name: Using PennyLane
    :link: introduction/pennylane.html
    :description: A guided tour of the core features of PennyLane
Index Card

Title Card

.. title-card::
    :name: 'lightning.qubit'
    :description: A fast state-vector qubit simulator written in C++
    :link: devices.html
Title Card

YouTube Video

<No example is available yet.>

Support

If you are having issues, please let us know by posting the issue on our Github issue tracker.

License

The Xanadu Sphinx Theme is free and open source, released under the Apache License, Version 2.0.

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

xanadu-sphinx-theme-0.5.0.tar.gz (21.5 kB view details)

Uploaded Source

Built Distribution

xanadu_sphinx_theme-0.5.0-py3-none-any.whl (50.6 kB view details)

Uploaded Python 3

File details

Details for the file xanadu-sphinx-theme-0.5.0.tar.gz.

File metadata

  • Download URL: xanadu-sphinx-theme-0.5.0.tar.gz
  • Upload date:
  • Size: 21.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for xanadu-sphinx-theme-0.5.0.tar.gz
Algorithm Hash digest
SHA256 6384dcd9cbcf4c5fdf4f3b75c9c4be5343eb24ce165d6f6db3295fb5fa19ae5d
MD5 55989600098381bc7e861facca9b8f4f
BLAKE2b-256 3d78734e2ac5957e71a77100652c148bf3263b8afc994c92c0c8263e97882fe5

See more details on using hashes here.

File details

Details for the file xanadu_sphinx_theme-0.5.0-py3-none-any.whl.

File metadata

File hashes

Hashes for xanadu_sphinx_theme-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 95f87d69d4df9d923a17b41a74a4038d85ee610db7ec5610a6cc70d839e0089f
MD5 0582dd0bfa1419c9ac472cb81ae78afa
BLAKE2b-256 2950363baa8e174804cef6dadf3a0db9a7ab3d4f9ac0da0f97953a77cd43e89f

See more details on using hashes here.

Supported by

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