edx-sphinx-theme

DEPRECATION WARNING

This Sphinx theme is now deprecated and will not recieve further updates. For details see https://github.com/openedx/edx-sphinx-theme/issues/184.

It is recommended that you switch to the sphinx-book-theme for any docs that you're writing that use this theme. Instructions to do so can be found here <https://docs.openedx.org/en/latest/developers/how-tos/switch-to-the-sphinx-book-theme.html>

Summary

edx-sphinx-theme is a Sphinx theme for Open edX documentation. It should be used for all documentation in repositories in the edx GitHub organization which is intended to be used with the Sphinx documentation system.

Overview

This theme makes the following changes to the default Sphinx output:

• Displays the edX logo
• Adds a link to a feedback form that identifies which page the feedback came from

To use edx-sphinx-theme for a repository's documentation:

• pip install edx-sphinx-theme or equivalent (add edx-sphinx-theme to any appropriate requirements files)
• Add edx_theme to the extensions list in conf.py (it adds the feedback form URL to the rendering context for each page).
• Update the html_theme and html_theme_path values in conf.py so the theme can be located and loaded.
• Set html_favicon to the path of the favicon.ico file in the theme.
• Use the AUTHOR constant where appropriate in conf.py (This default is only provided as a convenience. The repository is free to use another value if appropriate).
• To add an "Edit on Github" link to every page, add a dict called html_context, as detailed in the following example.

For example:

import os
import edx_theme

extensions = ['edx_theme']

copyright = '{year}, edX Inc.'.format(year=datetime.datetime.now().year)
author = edx_theme.AUTHOR

html_theme = 'edx_theme'
html_theme_path = [edx_theme.get_html_theme_path()]
html_favicon = os.path.join(html_theme_path[0], 'edx_theme', 'static', 'css', 'favicon.ico')

latex_documents = [
    (master_doc, 'edx-sphinx-theme.tex', 'edx-sphinx-theme Documentation',
     author, 'manual'),
]

html_context = {
    "display_github": True, # Integrate GitHub
    "github_user": "edx", # Username
    "github_repo": 'edx-sphinx-theme', # Repo name
    "github_version": "master", # Version
    "conf_py_path": "/docs/", # Path in the checkout to the docs root
}

Read the Docs Configuration

Because this theme is a Python package which needs to be installed, Read the Docs needs to be configured appropriately to be able to install it when performing documentation builds. Under Advanced Settings:

• Install your project inside a virtualenv using setup.py install should be checked
• Requirements file should point to a pip requirements file which includes open-edx-theme.

Documentation

The full documentation is at https://edx-sphinx-theme.readthedocs.org.

License

The code in this repository is licensed under the Apache Software License 2.0 unless otherwise noted.

Please see LICENSE.txt for details.

How To Contribute

Contributions are very welcome.

Please read How To Contribute for details.

Reporting Security Issues

Please do not report security issues in public. Please email security@edx.org.

Getting Help

Have a question about this repository, or about Open edX in general? Please refer to this list of resources if you need any assistance.