How To Add Sphinx Docs to a Repo#

This how-to will help you setup the basic skeleton for sphinx docs in your repo in a manner that is standard to the Open edX Project.


  • You know how to use Git

  • You are familiar enough with make to use it.

  • You are familiar with basic python development (pip, virtualenvs, etc.)


  1. Add a file in the requirements folder with the following content.

    # Requirements to build the documentation.
    -c constraints.txt
  2. Add to the upgrade command in your Makefile

  3. Run make upgrade to generate requirements/docs.txt

  4. pip install -r requirements/docs.txt

  5. Make a docs folder at the root of your repo and cd into it.


    If you already have a docs repo with RST, move it aside for now, and you can move the RST files into the newly generated sphinx project once it has been setup.

    mkdir docs
    cd docs
  6. Generate a basic sphinx doc skeleton.

    sphinx-quickstart --no-batchfile --extensions sphinxcontrib.contentui --extensions sphinx_copybutton --extensions sphinx.ext.graphviz --extensions sphinxcontrib.mermaid --no-sep -a "Open edX Community" -l "en" --release latest
  7. Make sure the build works.

    make html

    This should generate an html file at _build/html/index.html

  8. Update the following settings in docs/

    html_theme = 'sphinx_book_theme'
  9. Add the following settings to docs/


    You’ll have to update at least the repository_url and repository_branch settings in html_theme_options but you should review the rest of the settings as well.

    import os
    html_theme_options = {
        "repository_url": TODO: Add a URL Here,
        "repository_branch": TODO: Add the correct branch here,
        "path_to_docs": "docs/",
        "use_repository_button": True,
        "use_issues_button": True,
        "use_edit_page_button": True,
        "extra_footer": """
            <a rel="license" href="">
                    alt="Creative Commons License"
            These works by
                >Axim Collaborative</a>
            are licensed under a
                >Creative Commons Attribution-ShareAlike 4.0 International License</a>.
    # 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 = ""
    html_favicon = ""
    # Set the DJANGO_SETTINGS_MODULE if it's not set.
    if not os.environ.get('DJANGO_SETTINGS_MODULE'):
       os.environ['DJANGO_SETTINGS_MODULE'] = 'test_utils.test_settings'
  10. Run the build again to make sure youve got the standard logos and footers setup.

    make html
  11. Now that the basic build works you’re ready to create the skeleton for documentation based on diataxis.

    cd docs/
    mkdir -p {concepts,how-tos,quickstarts,references,decisions}
    touch {concepts,how-tos,quickstarts,references,decisions}/index.rst
  12. Add a title to each index.rst

  13. Start wiriting documentation!

See also

Quick Reference: Writing RST

Basic syntax guidance for RST.


The conceptual documentation system we’re trying to follow.

Documentation Content Types

A quick summary on the different types of documents.

How-to get your repository docs on

Once your docs are building, setup publishing and PR builds.