How to Switch to the sphinx-book-theme for Documentation
########################################################
This how-to will help you switch from your existing Sphinx theme to the
sphinx-book-theme for a sphinx documentation project.
Assumptions
***********
.. This section should contain a bulleted list of assumptions you have of the
person who is following the How-to. The assumptions may link to other
how-tos if possible.
* You already have a Sphinx documentation project.
* You know how to work with Python code.
Steps
*****
.. A task should have 3 - 7 steps. Tasks with more should be broken down into digestible chunks.
#. Update and rebuild your requirements.
#. Find the requirements file that has your documentation requirements in it.
For most projects there will be a ``requirements/docs.in`` file which will
contain your theme as a Python requirement. For example if you are using
the deprecated ``edx-sphinx-theme``, you'll see a line with that package
name on it.
#. Remove your old theme (for example, ``edx-sphinx-theme``) and add a line for the
``sphinx-book-theme``.
.. code::
- edx-sphinx-theme
+ sphinx-book-theme
#. Run ``make upgrade``
#. Install your doc requirements.
.. code::
pip install -r requirements/docs.txt # in most cases
#. Update conf.py
Add or update the following
.. code::
import os
html_theme_options = {
"repository_url": TODO: Add a github URL Here, for example https://github.com/openedx/repo-name,
"repository_branch": TODO: Add the correct branch, for example 'main',
"path_to_docs": "docs/",
"logo_only": True,
"home_page_in_toc": True,
"use_repository_button": True,
"use_issues_button": True,
"use_edit_page_button": True,
# Please don't change unless you know what you're doing.
"extra_footer": """
These works by
The Center for Reimagining Learning
are licensed under a
Creative Commons Attribution-ShareAlike 4.0 International License.
"""
}
# Note the logo won't show up properly yet because there is an upstream
# bug in the theme that needs to be fixed first.
# If you'd like you can temporarily copy the logo file to your `_static`
# directory.
html_logo = "https://logos.openedx.org/open-edx-logo-color.png"
html_favicon = "https://logos.openedx.org/open-edx-favicon.ico"
# Set the DJANGO_SETTINGS_MODULE if it's not set.
# Only if your project has a dependency on Django
if not os.environ.get('DJANGO_SETTINGS_MODULE'):
# If you do depend on django you'll need a settings file that you can
# use when building docs. This will allow you to pull docstrings from
# your code.
os.environ['DJANGO_SETTINGS_MODULE'] = 'test_utils.test_settings'
#. Re-build your project and fix any errors.
.. code::
make html # and fix errors until there are no errors.
Once everything is building correctly without errors you should be all set to
make a pull request with your changes!
.. Following the steps, you should add the result and any follow-up tasks needed.
.. seealso::
:doc:`add-sphinx-docs-to-a-repo`