From 7f40a24611bdb2a65c737a0a7331cd23c762609f Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Mon, 20 Apr 2020 23:45:02 +0100 Subject: [PATCH] ENH: Improve versions dropdown closes #22 --- docs/Makefile | 159 ++---------------- docs/conf.py | 6 + docs/customization.rst | 105 +++++++++--- docs/numpydoc.rst | 2 +- setup.py | 6 +- sphinx_material/__init__.py | 4 +- sphinx_material/sphinx_material/header.html | 1 + sphinx_material/sphinx_material/layout.html | 1 - sphinx_material/sphinx_material/theme.conf | 5 + .../sphinx_material/version_dropdown.html | 11 ++ 10 files changed, 126 insertions(+), 174 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 9ef8daa..d2a8238 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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 ' where 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) diff --git a/docs/conf.py b/docs/conf.py index d50cbdd..12fc74c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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: diff --git a/docs/customization.rst b/docs/customization.rst index 9f2f622..24de288 100644 --- a/docs/customization.rst +++ b/docs/customization.rst @@ -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 @@ -90,13 +90,16 @@ 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 @@ -104,7 +107,8 @@ The search box, the global toc and the local toc all respect the value in ``html "**": ["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 @@ -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: @@ -161,18 +165,81 @@ customization: (e.g., `FontAwesome `_). 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 `. + +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. diff --git a/docs/numpydoc.rst b/docs/numpydoc.rst index d9ebef5..df967bd 100644 --- a/docs/numpydoc.rst +++ b/docs/numpydoc.rst @@ -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:: diff --git a/setup.py b/setup.py index 2dc5ab1..b04575e 100644 --- a/setup.py +++ b/setup.py @@ -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",]}, ) diff --git a/sphinx_material/__init__.py b/sphinx_material/__init__.py index c611bac..2b072ff 100644 --- a/sphinx_material/__init__.py +++ b/sphinx_material/__init__.py @@ -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, diff --git a/sphinx_material/sphinx_material/header.html b/sphinx_material/sphinx_material/header.html index 946d0f4..7c49b4d 100644 --- a/sphinx_material/sphinx_material/header.html +++ b/sphinx_material/sphinx_material/header.html @@ -34,6 +34,7 @@ {% endif %} + {% include "version_dropdown.html" %} diff --git a/sphinx_material/sphinx_material/layout.html b/sphinx_material/sphinx_material/layout.html index e0d55fe..e86343c 100644 --- a/sphinx_material/sphinx_material/layout.html +++ b/sphinx_material/sphinx_material/layout.html @@ -59,7 +59,6 @@ {% endif %} {{ super() }} - {% include "version_dropdown.html" %} {% endblock %} {%- block header %} diff --git a/sphinx_material/sphinx_material/theme.conf b/sphinx_material/sphinx_material/theme.conf index 3447e0f..b0b7aa4 100644 --- a/sphinx_material/sphinx_material/theme.conf +++ b/sphinx_material/sphinx_material/theme.conf @@ -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" diff --git a/sphinx_material/sphinx_material/version_dropdown.html b/sphinx_material/sphinx_material/version_dropdown.html index eec0b93..f2f77a6 100644 --- a/sphinx_material/sphinx_material/version_dropdown.html +++ b/sphinx_material/sphinx_material/version_dropdown.html @@ -1,4 +1,14 @@ {% if theme_version_dropdown %} + {% if theme_version_info %} +
+ +
+ {%- for title, href in theme_version_info.items() %} + {{ title }} + {% endfor %} +
+
+ {% else %} + {% endif %} {% endif %}