django-sphinx-hosting
expects your Sphinx docs to be in a specific format to
be able to be imported, and to be built with specific sphinx extensions. On
this page, we describe how to configure your Sphinx project appropriately.
To import a documentation set, there must be a
:py:class:`sphinx_hosting.models.Project` in the database whose machine_name
matches the project
in Sphinx's conf.py
config file for the docs to be
imported. The machine_name
for a project is set at project create time within
django-sphinx-hosting
.
Create a project by navigating to the "Projects" page and clicking the "Create
Project" button. You'll be asked for a human name, a machine name and a
description. Whatever you use for your version control repository name is a
good choice for Machine Name
.
The release
in the conf.py
will be used to create or update a
:py:class:`sphinx_hosting.models.Version`. We will set
:py:attr:`sphinx_hosting.models.Version.version` to the value of release
.
Miminally, you must use the Sphinx ReadTheDocs theme when packaging your documentation. The importers, views and stylesheets inside django-sphinx-hosting depend on the HTML structure, Javascript and CSS classes that that theme provides.
Ensure that you have html_theme_options["collapse_navigation"]
set to
False
, otherwise your auto-built navigation within django-sphinx-hosting
may look wrong.
extensions = [
'sphinx_rtd_theme',
...
]
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
"collapse_navigation": False
}
If you have a complex page hierarchy in your documentation, you may benefit from
sphinxcontrib-jsonglobaltoc. This extension
extends :py:class:`JSONHTMLBuilder` from sphinxcontrib-serializinghtml
to
add a globaltoc
key to each .fjson
file produced. globaltoc
contains the HTML for the global table of contents for the entire set of
documentation. This allows django-sphinx-hosting to more reliably build your
navigation.
extensions = [
'sphinx_rtd_theme',
'sphinx_json_globaltoc'
...
]