Skip to content

Commit

Permalink
Merge pull request SymbiFlow#45 from bashtage/improve-versions
Browse files Browse the repository at this point in the history
ENH: Improve versions dropdown
  • Loading branch information
bashtage authored Apr 21, 2020
2 parents 22f4820 + 7f40a24 commit baf1d5f
Show file tree
Hide file tree
Showing 10 changed files with 126 additions and 174 deletions.
159 changes: 13 additions & 146 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -1,153 +1,20 @@
# Makefile for Sphinx documentation
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?= -j auto
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build

# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext

# Put it first so that "make" without argument is like "make help".
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"

clean:
-rm -rf $(BUILDDIR)/*

html:
$(SPHINXBUILD) -j auto -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."

json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."

htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."

qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/AWSSDKforPHP.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/AWSSDKforPHP.qhc"

devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/AWSSDKforPHP"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/AWSSDKforPHP"
@echo "# devhelp"

epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."

latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."

man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."

info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: help Makefile

doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -j auto $(SPHINXOPTS) $(O)
6 changes: 6 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,12 @@
},
"version_dropdown": True,
"version_json": "_static/versions.json",
"version_info": {
"Release": "https://bashtage.github.io/sphinx-material/",
"Development": "https://bashtage.github.io/sphinx-material/devel/",
"Release (rel)": "/",
"Development (rel)": "/devel/",
},
}

if FORCE_CLASSIC:
Expand Down
105 changes: 86 additions & 19 deletions docs/customization.rst
Original file line number Diff line number Diff line change
Expand Up @@ -77,9 +77,9 @@ Configuration Options
``nav_links``
A list of dictionaries where each has three keys:

- ``'href'``: The URL or pagename (str)
- ``'title'``: The title to appear (str)
- ``'internal'``: Flag indicating to use pathto to find the page. Set to False for
- ``href``: The URL or pagename (str)
- ``title``: The title to appear (str)
- ``internal``: Flag indicating to use pathto to find the page. Set to False for
external content. (bool)
``heroes``
A ``dict[str,str]`` where the key is a pagename and the value is the text to display in the
Expand All @@ -90,21 +90,25 @@ Configuration Options
``version_dropdown_text``
The text in the version dropdown button
``version_json``
The location of the JSON file that contains the version information. The defaulta ssumes there
The location of the JSON file that contains the version information. The default assumes there
is a file versions.json located in the root of the site.
``version_info``
A dictionary used to populate the version dropdown. If this variable is provided, the static
dropdown is used and any JavaScript information is ignored.


Removing sidebars
=================
The search box, the global toc and the local toc all respect the value in ``html_sidebars`` in ``conf.py``. The default setting is
Sidebars
========
You must set ``html_sidebars`` in order for the side bar to appear. There are
four in the complete set.

.. code-block:: python
html_sidebars = {
"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
}
If this is changed to
You can exclude any to hide a specific sidebar. For example, if this is changed to

.. code-block:: python
Expand Down Expand Up @@ -147,7 +151,7 @@ Finally, edit your override file ``source/_templates/layout.html``:
{%- endblock %}
New Blocks
----------
==========
The theme has a small number of new blocks to simplify some types of
customization:

Expand All @@ -161,18 +165,81 @@ customization:
(e.g., `FontAwesome <https://fontawesome.com/>`_). You should probably call ``{{ super() }}`` at
the end of the block to include the default icon font as well.

Older Versions
--------------
.. note::
Version Dropdown
================

A version dropdown is available that lets you store multiple versions in a single site.
The standard structure of the site, relative to the base is usually::

/
/devel
/v1.0.0
/v1.1.0
/v1.1.1
/v1.2.0


This feature is experimental and the implementation may change.
To use the version dropdown, you must set ``version_dropdown`` to ``True`` in
the sites configuration.

A dropdown memu an be used to switch to older version. The data used is read via javascript from
a file. The basic structure of the file is a dictionary of the form [label, path].
There are two approaches, one which stores the version information in a JavaScript file
and one which uses a dictionary in the configuration.

Using a Javascript File
-----------------------
The data used is read via javascript from a file. The basic structure of the file is a dictionary of the form [label, path].

.. code-block::javascript
{"release": "", "development": "devel"}
{
"release": "",
"development": "devel",
"v1.0.0": "v1.0.0",
"v1.1.0": "v1.1.0",
"v1.1.1": "v1.1.0",
"v1.2.0": "v1.2.0",
}
This dictionary tells the dropdown that the release version is in the root of the site, the
other versions are archived under their version number, and the development version is
located in /devel.

.. note::

The advantage of this approach is that you can separate version information
from the rendered documentation. This makes is easy to change the version
dropdown in _older_ versions of the documentation to reflect additional versions
that are released later. Changing the Javascript file changes the version dropdown
content in all versions. This approach is used in
`statsmodels <https://www.statsmodels.org/>`.

Using ``conf.py``
-----------------

.. warning::

This method has precedence over the JavaScript approach. If ``version_info`` is
not empty in a site's ``html_theme_options``, then the static approach is used.

The alternative uses a dictionary where the key is the title and the value is the target.
The dictionary is part of the size configuration's ``html_theme_options``.

.. code-block::python
"version_info": {
"release": "/",
"development": "/devel/",
"v1.0.0": "/v1.0.0/",
"v1.1.0": "/v1.1.0/",
"v1.1.1": "/v1.1.0/",
"v1.2.0": "/v1.2.0/",
"Read The Docs": "https://rtd.readthedocs.io/",
}
The dictionary structure is nearly identical. Here you can use relative paths
like in the JavaScript version. You can also use absolute paths.

.. note::

This dictionary tells the dropdown that the release version is in the root of the site and the
development version is located in /devel.
This approach is easier if you only want to have a fixed set of documentation,
e.g., stable and devel.
2 changes: 1 addition & 1 deletion docs/numpydoc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
NumPy Docstrings
================

This page shows how ``autosummary`` works wiht ``numpydoc`` and a
This page shows how ``autosummary`` works with ``numpydoc`` and a
NumPy-style docstring.

.. autosummary::
Expand Down
6 changes: 1 addition & 5 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,5 @@
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
],
entry_points={
'sphinx.html_themes': [
'sphinx_material = sphinx_material',
]
},
entry_points={"sphinx.html_themes": ["sphinx_material = sphinx_material",]},
)
4 changes: 2 additions & 2 deletions sphinx_material/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ def setup(app):
app.sitemap_links = sitemap_links
app.site_pages = site_pages
app.add_html_theme(
'sphinx_material',
os.path.join(html_theme_path()[0], 'sphinx_material'))
"sphinx_material", os.path.join(html_theme_path()[0], "sphinx_material")
)
return {
"version": __version__,
"parallel_read_safe": True,
Expand Down
1 change: 1 addition & 0 deletions sphinx_material/sphinx_material/header.html
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
</div>
</div>
{% endif %}
{% include "version_dropdown.html" %}
</div>
</nav>
</header>
1 change: 0 additions & 1 deletion sphinx_material/sphinx_material/layout.html
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@
<link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}"/>
{% endif %}
{{ super() }}
{% include "version_dropdown.html" %}
{% endblock %}

{%- block header %}
Expand Down
5 changes: 5 additions & 0 deletions sphinx_material/sphinx_material/theme.conf
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,11 @@ version_dropdown = False
# Text to use in the dropdown menu
version_dropdown_text = Versions

# Optional dictionary that to use when populating the version dropdown.
# The key is the text that appears, and the value is the absolute path
# of the alternative versions
version_info =

# Relative path to json file. The default is "versions.json" which assumes the
# file hosted in the root of the site. You can use other file names or locations, e.g.,
# "_static/old_versions.json"
Expand Down
Loading

0 comments on commit baf1d5f

Please sign in to comment.