docs: Add optional sphinx_rtd_theme; add docs build instructions.

The sphinx_rtd_theme is used by ReadTheDocs to render a pretty looking
documentation.  If you have this theme installed locally then your
locally-compiled docs will look exactly like the published
documentation.   Otherwise it falls back to the default theme.
This commit is contained in:
evildmp 2014-11-06 00:14:26 +00:00 committed by Damien George
parent ca0b0cb83f
commit aec189a5ba
2 changed files with 29 additions and 6 deletions

View File

@ -98,3 +98,18 @@ AUR. If the above does not work it may be because you don't have the
correct permissions. Try then:
$ sudo dfu-util -a 0 -d 0483:df11 -D build-PYBV10/firmware.dfu
Building the documentation locally
----------------------------------
Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme,
preferably in a virtualenv:
pip install sphinx
pip install sphinx_rtd_theme
In `micropython/docs`, build the docs:
make html
You'll find the index page at `micropython/docs/build/html/index.html`.

20
docs/conf.py Normal file → Executable file
View File

@ -103,9 +103,17 @@ pygments_style = 'sphinx'
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# on_rtd is whether we are on readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
try:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
except:
html_theme = 'default'
html_theme_path = ['.']
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -113,7 +121,7 @@ html_theme = 'default'
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['.']
# html_theme_path = ['.']
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
@ -154,7 +162,7 @@ html_last_updated_fmt = '%d %b %Y'
# Additional templates that should be rendered to pages, maps page names to
# template names.
html_additional_pages = {"index":"topindex.html"}
html_additional_pages = {"index": "topindex.html"}
# If false, no module index is generated.
#html_domain_indices = True
@ -234,7 +242,7 @@ latex_documents = [
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'micropython', 'Micro Python Documentation',
['Damien P. George'], 1)
['Damien P. George'], 1),
]
# If true, show URL addresses after external links.