Introduction
============
|PyPi| |Waf Python Tests| |Black| |Flake8| |Pip Install|
.. |PyPi| image:: https://badge.fury.io/py/versjon.svg
:target: https://badge.fury.io/py/versjon
.. |Waf Python Tests| image:: https://github.com/steinwurf/versjon/actions/workflows/waf.yml/badge.svg
:target: https://github.com/steinwurf/versjon/actions/workflows/waf.yml
.. |Flake8| image:: https://github.com/steinwurf/versjon/actions/workflows/flake8.yml/badge.svg
:target: https://github.com/steinwurf/versjon/actions/workflows/flake8.yml
.. |Black| image:: https://github.com/steinwurf/versjon/actions/workflows/black.yml/badge.svg
:target: https://github.com/steinwurf/versjon/actions/workflows/black.yml
.. |Pip Install| image:: https://github.com/steinwurf/versjon/actions/workflows/pip.yml/badge.svg
:target: https://github.com/steinwurf/versjon/actions/workflows/pip.yml
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:
* ``versjon`` works by injecting some basic HTML in to the generated
documentation.
Demonstration
-------------
.. image:: demo.gif
Installation
------------
1. Install the ``versjon`` tool using ``pip``::
python -m pip install versjon
Building the docs
-----------------
1. Build all the different versions of your documentation into a common
directory. For example generating all the docs in the ``site`` directory::
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.1
``versjon`` will use whatever ``version`` is specified in the Sphinx
configuration: https://www.sphinx-doc.org/en/master/usage/configuration.html
If you have the specified the ``version`` number in ``conf.py`` you can omit
the ``-D version`` option to Sphinx build.
2. Run ``versjon`` in the common directory - and you are done.
Index page
----------
As default ``versjon`` will generate an ``index.html`` file 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-index`` option.
Stable index
------------
As default ``versjon`` will generate a folder in the documentation root called
``stable``. This folder will contain an ``index.html`` with a redirect to the
latest stable version. You can disable this behavior with
``--no-stable-index`` option.
Built in templates (injection)
------------------------------
``versjon`` ships 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 an ``index.html``
in the ``root`` folder. In this template you have access to the
following variables: ``general``, ``page``.
* ``stable_index.html``: This template is use to generate an ``index.html``
in the ``stable`` folder. In this template you have access to the
following variables: ``general``, ``page``.
Customization
-------------
You 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.html`` one and adapt it.
If you want to "inject" a custom footer. Create a file called ``footer.html``
and put it somewhere in your project, e.g., ``mydocs/footer.html`` now invoke
``versjon`` with the ``--user_templates`` argument, e.g.,::
./versjon --user_templates=mydocs
``verjson`` will 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.html`` if
the template is empty no content will be injected.
The ``context``
---------------
In 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 variables
.................
* ``semver``: 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 the ``other`` list will contain branches.
* ``stable``: If we have any semantic version releases the ``stable`` version
will be the newest release in the ``semver`` list.
* ``docs_path``: Dictionary mapping versions to the build folder for a version
relative to the documentation root.
Build variables
...............
* ``current``: The current version name
* ``is_semver``: True if the current version follows semantic versioning
Page variables
..............
* ``page_root``: Relative path to the documentation root from a given HTML
page.
Concatenating the ``page_root`` with a path in ``docs_path`` will give a
valid relative link from one HTML page to the root folder of specific
version.
Raw data
{
"_id": null,
"home_page": "https://github.com/steinwurf/",
"name": "versjon",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "versjon",
"author": "Steinwurf ApS",
"author_email": "contact@steinwurf.com",
"download_url": "",
"platform": null,
"description": "Introduction\n============\n\n|PyPi| |Waf Python Tests| |Black| |Flake8| |Pip Install|\n\n.. |PyPi| image:: https://badge.fury.io/py/versjon.svg\n :target: https://badge.fury.io/py/versjon\n\n.. |Waf Python Tests| image:: https://github.com/steinwurf/versjon/actions/workflows/waf.yml/badge.svg\n :target: https://github.com/steinwurf/versjon/actions/workflows/waf.yml\n\n.. |Flake8| image:: https://github.com/steinwurf/versjon/actions/workflows/flake8.yml/badge.svg\n :target: https://github.com/steinwurf/versjon/actions/workflows/flake8.yml\n\n.. |Black| image:: https://github.com/steinwurf/versjon/actions/workflows/black.yml/badge.svg\n :target: https://github.com/steinwurf/versjon/actions/workflows/black.yml\n\n.. |Pip Install| image:: https://github.com/steinwurf/versjon/actions/workflows/pip.yml/badge.svg\n :target: https://github.com/steinwurf/versjon/actions/workflows/pip.yml\n\nWhat it is:\n\n* A tool for linking multiple versions of your project's Sphinx\n documentation, without the need for special services such as readthedocs.org.\n* Useful if you build and host your documentation as a static site.\n\nHow it works:\n\n* ``versjon`` works by injecting some basic HTML in to the generated\n documentation.\n\nDemonstration\n-------------\n\n.. image:: demo.gif\n\nInstallation\n------------\n\n1. Install the ``versjon`` tool using ``pip``::\n\n python -m pip install versjon\n\nBuilding the docs\n-----------------\n\n1. Build all the different versions of your documentation into a common\n directory. For example generating all the docs in the ``site`` directory::\n\n git checkout 2.0.0\n sphinx-build... -D version=2.0.0 ... site/build_2.0.0\n\n ...\n\n git checkout 5.1.1\n sphinx-build... -D version=5.1.1 ... site/build_5.1.1\n\n\n ``versjon`` will use whatever ``version`` is specified in the Sphinx\n configuration: https://www.sphinx-doc.org/en/master/usage/configuration.html\n If you have the specified the ``version`` number in ``conf.py`` you can omit\n the ``-D version`` option to Sphinx build.\n\n2. Run ``versjon`` in the common directory - and you are done.\n\nIndex page\n----------\n\nAs default ``versjon`` will generate an ``index.html`` file with a redirect to\nthe latest stable version, or if no semver version exists the first branch,\npresumably the master.\nYou can disable this behavior with ``--no-index`` option.\n\nStable index\n------------\n\nAs default ``versjon`` will generate a folder in the documentation root called\n``stable``. This folder will contain an ``index.html`` with a redirect to the\nlatest stable version. You can disable this behavior with\n``--no-stable-index`` option.\n\nBuilt in templates (injection)\n------------------------------\n\n``versjon`` ships with a couple of built-in templates, that get injected\nin the generated HTML:\n\n* ``head.html``: This template gets injected into the ``<head>`` tag of\n the generated HTML pages. In this template you have access to the following\n variables: ``general``, ``build``, ``page``.\n* ``header.html``: This template is inject at the beginning of the ``<body>``\n tag. In this template you have access to the following variables:\n ``general``, ``build``, ``page``.\n* ``footer.html``: This template is inject at the end of the ``<body>``\n tag. In this template you have access to the following variables:\n ``general``, ``build``, ``page``.\n* ``index.html``: This template is use to generate an ``index.html``\n in the ``root`` folder. In this template you have access to the\n following variables: ``general``, ``page``.\n* ``stable_index.html``: This template is use to generate an ``index.html``\n in the ``stable`` folder. In this template you have access to the\n following variables: ``general``, ``page``.\n\nCustomization\n-------------\nYou can provide you own template for generating the version selector etc.\n\nThe easiest way is probably to copy one of the default HTML templates, e.g.,\n``src/templates/footer.html`` one and adapt it.\n\nIf you want to \"inject\" a custom footer. Create a file called ``footer.html``\nand put it somewhere in your project, e.g., ``mydocs/footer.html`` now invoke\n``versjon`` with the ``--user_templates`` argument, e.g.,::\n\n ./versjon --user_templates=mydocs\n\n``verjson`` will prioritize finding templates in the users path first. If none\nis found it will fallback to the built-in.\n\nIf you want to disable a built-in template, simply create an empty file with\nthe same name as the template you want to disable e.g. ``header.html`` if\nthe template is empty no content will be injected.\n\nThe ``context``\n---------------\n\nIn the templates you can access the information gathered by versjon. Based on\nthis you can generate the needed HTML.\n\nThe following lists the various variables.\n\nGeneral variables\n.................\n\n* ``semver``: A list of version dicts with a name which is a valid sematic\n version numbers, and a list of available files in this version.\n* ``other``: A list of version dicts with a name which non-semantic version\n numbers, and a list of available files in this version.\n Typically the ``other`` list will contain branches.\n* ``stable``: If we have any semantic version releases the ``stable`` version\n will be the newest release in the ``semver`` list.\n* ``docs_path``: Dictionary mapping versions to the build folder for a version\n relative to the documentation root.\n\nBuild variables\n...............\n\n* ``current``: The current version name\n* ``is_semver``: True if the current version follows semantic versioning\n\nPage variables\n..............\n\n* ``page_root``: Relative path to the documentation root from a given HTML\n page.\n Concatenating the ``page_root`` with a path in ``docs_path`` will give a\n valid relative link from one HTML page to the root folder of specific\n version.\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-clause \"New\" or \"Revised\" License",
"summary": "Tool for generating a json file with the name and url of versions.",
"version": "2.3.0",
"split_keywords": [
"versjon"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "a63e7e33cb6ea180cc5779440ae01df4",
"sha256": "a35b88d6bbe519f21cc23200b41824ef235cd7ebde2fb1effe3f69ebc832a697"
},
"downloads": -1,
"filename": "versjon-2.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a63e7e33cb6ea180cc5779440ae01df4",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 10075,
"upload_time": "2022-12-14T12:00:38",
"upload_time_iso_8601": "2022-12-14T12:00:38.986065Z",
"url": "https://files.pythonhosted.org/packages/66/14/d7dfb484a8a8f649540bba23adbec340acb0951ad2dafe4011ad2f440ee8/versjon-2.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-14 12:00:38",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "versjon"
}
JSON