Skip to content

Commit

Permalink
Use sphinx_multiversion to make multiversioned docs
Browse files Browse the repository at this point in the history
sphinx-multiversion can build a copy of the documentation for each tag
and place in a subfolder. The existing spinx setup can build the top
level latest version. versioning.html gives links to version in the
sidebar. layout.html overrides the main template to use correct versions
in the title and top navigation bar.

Note this requires a patch to sphinx_multiversion to allow calling a
prebuild command. This is used to call the docs_api for each checkout.
sphinx-contrib/multiversion#62
  • Loading branch information
samtygier-stfc authored and Dimitar Tasev committed Dec 18, 2020
1 parent 3bbf042 commit 801d32a
Show file tree
Hide file tree
Showing 6 changed files with 59 additions and 10 deletions.
1 change: 1 addition & 0 deletions deps/dev-requirements.pip
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ gitpython == 3.1.0
flake8
pylint
sphinx
sphinx-multiversion
mypy
yapf
pytest
Expand Down
1 change: 1 addition & 0 deletions docs/_static/extra.css
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
div.versions {margin-top: 10px}
17 changes: 17 additions & 0 deletions docs/_templates/layout.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{%- extends "!layout.html" %}
{%- block htmltitle %}
{% if versions %}
<title>{{ title|striptags|e }} - {{ project }} {{ current_version.name }} Documentation</title>
{% else %}
<title>{{ title|striptags|e }}{{ titlesuffix }}</title>
{% endif %}
{%- endblock %}

{%- block rootrellink %}
{% if versions %}
<li class="nav-item nav-item-0"><a href="{{ pathto(master_doc)|e }}">{{ project }} {{ current_version.name }} Documentation</a>{{ reldelim1 }}</li>
{% else %}
<li class="nav-item nav-item-0"><a href="{{ pathto(master_doc)|e }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
{% endif %}
{%- endblock %}

21 changes: 21 additions & 0 deletions docs/_templates/versioning.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{% if versions %}
<div class="versions">
<h3>{{ _('Versions') }}</h3>
<ul>
<li><a href="../{{ pathto("",1)}}index.html">Latest</a></li>
{%- for item in versions %}
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
{%- endfor %}
</ul>
</div>
{% else %}
<div class="versions">
<h3>{{ _('Versions') }}</h3>
<ul>
<li><a href="{{ pathto("",1)}}index.html">Latest</a></li>
{%- for item in ['0.9.0', '1.0.0', '1.1.0'] %}
<li><a href="{{ pathto("",1)}}{{ item }}/index.html">{{ item }}</a></li>
{%- endfor %}
</ul>
</div>
{% endif %}
26 changes: 17 additions & 9 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,15 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage',
'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.imgmath'
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'sphinx.ext.imgmath',
'sphinx_multiversion',
]

# Add any paths that contain templates here, relative to this directory.
Expand Down Expand Up @@ -87,13 +94,7 @@
# a list of builtin themes.
html_theme = 'classic'

html_sidebars = {
'**': [
'localtoc.html',
'relations.html',
'searchbox.html',
]
}
html_sidebars = {'**': ['localtoc.html', 'relations.html', 'searchbox.html', 'versioning.html']}

# 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
Expand All @@ -106,6 +107,7 @@
html_static_path = ['_static']

# -- Options for HTMLHelp output ------------------------------------------
html_css_files = ['extra.css']

# Output file base name for HTML help builder.
htmlhelp_basename = 'MantidImagingdoc'
Expand Down Expand Up @@ -158,3 +160,9 @@

# Stop sphinx from being a smartypants and merging the -- into a single unicode dash
html_use_smartypants = False

# sphinx-multiversion
smv_tag_whitelist = r'^\d+\.\d+\.\d+$' # tags that look like versions
smv_branch_whitelist = None # No branches
smv_released_pattern = r''
smv_prebuild_command = "python setup.py docs_api"
3 changes: 2 additions & 1 deletion environment.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ dependencies:
- mock
- pylint
- sphinx
- sphinx-multiversion
- pytest-randomly
- pytest-parallel
- psutil
- isort
- isort

0 comments on commit 801d32a

Please sign in to comment.