Package: versjon
What it is:A tool for linking multiple versions of your project’s Sphinx
documentation, without the need for special services such as readthedocs.org.Useful if you build and host your documentation as a static site.How it works:versjonworks by injecting some basic HTML in to the generated
documentation.DemonstrationInstallationInstall theversjontool usingpip:python -m pip install versjonBuilding the docsBuild all the different versions of your documentation into a common
directory. For example generating all the docs in thesitedirectory:git checkout 2.0.0
sphinx-build... -D version=2.0.0 ... site/build_2.0.0

...

git checkout 5.1.1
sphinx-build... -D version=5.1.1 ... site/build_5.1.1versjonwill use whateverversionis specified in the Sphinx
configuration:https://www.sphinx-doc.org/en/master/usage/configuration.htmlIf you have the specified theversionnumber inconf.pyyou can omit
the-Dversionoption to Sphinx build.Runversjonin the common directory - and you are done.Index pageAs defaultversjonwill generate anindex.htmlfile with a redirect to
the latest stable version, or if no semver version exists the first branch,
presumably the master.
You can disable this behavior with--no-indexoption.Stable indexAs defaultversjonwill generate a folder in the documentation root calledstable. This folder will contain anindex.htmlwith a redirect to the
latest stable version. You can disable this behavior with--no-stable-indexoption.Built in templates (injection)versjonships with a couple of built-in templates, that get injected
in the generated HTML:head.html: This template gets injected into the<head>tag of
the generated HTML pages. In this template you have access to the following
variables:general,build,page.header.html: This template is inject at the beginning of the<body>tag. In this template you have access to the following variables:general,build,page.footer.html: This template is inject at the end of the<body>tag. In this template you have access to the following variables:general,build,page.index.html: This template is use to generate anindex.htmlin therootfolder.  In this template you have access to the
following variables:general,page.stable_index.html: This template is use to generate anindex.htmlin thestablefolder.  In this template you have access to the
following variables:general,page.CustomizationYou can provide you own template for generating the version selector etc.The easiest way is probably to copy one of the default HTML templates, e.g.,src/templates/footer.htmlone and adapt it.If you want to “inject” a custom footer. Create a file calledfooter.htmland put it somewhere in your project, e.g.,mydocs/footer.htmlnow invokeversjonwith the--user_templatesargument, e.g.,:./versjon --user_templates=mydocsverjsonwill prioritize finding templates in the users path first. If none
is found it will fallback to the built-in.If you want to disable a built-in template, simply create an empty file with
the same name as the template you want to disable e.g.header.htmlif
the template is empty no content will be injected.ThecontextIn the templates you can access the information gathered by versjon. Based on
this you can generate the needed HTML.The following lists the various variables.General variablessemver: A list of version dicts with a name which is a valid sematic
version numbers, and a list of available files in this version.other: A list of version dicts with a name which non-semantic version
numbers, and a list of available files in this version.
Typically theotherlist will contain branches.stable: If we have any semantic version releases thestableversion
will be the newest release in thesemverlist.docs_path: Dictionary mapping versions to the build folder for a version
relative to the documentation root.Build variablescurrent: The current version nameis_semver: True if the current version follows semantic versioningPage variablespage_root: Relative path to the documentation root from a given HTML
page.
Concatenating thepage_rootwith a path indocs_pathwill give a
valid relative link from one HTML page to the root folder of specific
version.