==================
Docs-Versions-Menu
==================
.. image:: https://img.shields.io/badge/goerz-docs__versions__menu-blue.svg?logo=github
:alt: Source code on Github
:target: https://github.com/goerz/docs_versions_menu
.. image:: https://img.shields.io/badge/docs-gh--pages-blue.svg
:alt: Documentation
:target: https://goerz.github.io/docs_versions_menu/
.. image:: https://img.shields.io/pypi/v/docs_versions_menu.svg
:alt: docs-versions-menu on the Python Package Index
:target: https://pypi.org/project/docs-versions-menu
.. image:: https://img.shields.io/conda/vn/conda-forge/docs-versions-menu.svg
:alt: docs-versions-menu on conda-forge
:target: https://anaconda.org/conda-forge/docs-versions-menu
.. image:: https://github.com/goerz/docs_versions_menu/workflows/Docs/badge.svg?branch=master
:alt: Docs
:target: https://github.com/goerz/docs_versions_menu/actions?query=workflow%3ADocs
.. image:: https://github.com/goerz/docs_versions_menu/workflows/PyPI/badge.svg?branch=master
:alt: PyPI
:target: https://github.com/goerz/docs_versions_menu/actions?query=workflow%3APyPI
.. image:: https://github.com/goerz/docs_versions_menu/workflows/Tests/badge.svg?branch=master
:alt: Tests
:target: https://github.com/goerz/docs_versions_menu/actions?query=workflow%3ATests
.. image:: https://codecov.io/gh/goerz/docs_versions_menu/branch/master/graph/badge.svg
:alt: Codecov
:target: https://codecov.io/gh/goerz/docs_versions_menu
.. image:: https://img.shields.io/badge/License-MIT-green.svg
:alt: MIT License
:target: https://opensource.org/licenses/MIT
A versions-menu for Sphinx_-based documentation.
Historically, many open source projects have hosted their documentation on `Read the Docs`_ (RTD). However, RTD has a fixed `build process <https://docs.readthedocs.io/en/stable/builds.html>`_ that is essentially limited to just running Sphinx_. Moreover, RTD will inject advertisements into your documentation.
A more flexible approach is to build the documentation with continuous integration (e.g., `Github Actions`_) and to deploy the result to `Github Pages`_ or any other static site hosting. There are no restrictions on the build process: it may involve make_, tox_, latex_, or any number of custom scripts to augment Sphinx_.
The one difficulty that comes with self-hosting project documentation is that out of the box, there is no support for showing multiple releases or branches of the project. This project aims to remedy this. It **provides a Sphinx extension and a command-line tool that work together to generate a dynamic versions-menu similar to that on RTD pages.**
.. image:: https://raw.githubusercontent.com/goerz/docs_versions_menu/master/docs/_static/docs-versions-menu-screenshot.png
:alt: Docs-Versions-Menu Screenshot
The different "Versions" derive from the folder structure of the hosted documentation, e.g., for `Github Pages`_, the folders in the root of the ``gh-pages`` branch. The ``docs-versions-menu`` command-line tool, running on the ``gh-pages`` branch or on the server hosting the documentation, collects the available versions based on the folders it sees.
The ``docs_versions_menu`` Sphinx extension, running during the Sphinx build process, adds Javascript to the documentation that will inject a menu to switch between the found versions. It can also show warnings for outdated or unreleased versions.
See the Docs-Versions-Menu documentation itself for a `live example <online_>`_.
Development of Docs-Versions-Menu happens on `Github`_.
You can read the full documentation online_.
Installation
------------
To install the latest released version of ``docs-versions-menu``, run:
.. code-block:: shell
pip install docs-versions-menu
Or, to install the latest development version of ``docs-versions-menu`` from `Github`_:
.. code-block:: shell
pip install git+https://github.com/goerz/docs_versions_menu.git@master#egg=docs_versions_menu
The ``docs-versions-menu`` package can also be installed through conda_, using
the conda-forge_ channel. See the `instructions in the Docs-Versions-Menu
Feedstock <conda-feedstock-instructions_>`_.
Usage
-----
Showing a versions-menu in your documentation requires two steps:
1. Add ``'docs_versions_menu'`` to the list of extensions in your Sphinx ``conf.py``.
This adds Javascript to your rendered documentation that displays a dynamic versions-menu based on information in a ``versions.json`` file it expects to find in the webroot of the hosted documentation, e.g. the root of the ``gh-pages`` branch.
2. Set up the deployment of the documentation such that it runs the ``docs-versions-menu`` command in the webroot.
The command creates the file ``versions.json`` that step 1 depends on by analyzing the folders it finds in the webroot.
How to invoke ``docs-versions-menu`` depends on the specifics of how the documentation is deployed:
* For `Github Actions`_ deploying to `Github Pages`_, check out the ``gh-pages`` branch, run ``docs-versions-menu``, and commit and push the resulting files.
See the `workflow file`_ for Docs-Versions-Menu's documentation.
* For Travis_ deploying to `Github Pages`_ with Doctr_, tell ``doctr deploy`` to invoke the ``docs-versions-menu`` command:
.. code-block:: shell
doctr deploy --command=docs-versions-menu --no-require-master --build-tags "$DEPLOY_DIR"
* For deployments to a static web host, use ``ssh`` to run the ``docs-versions-menu`` command on the server
See the `full documentation <online_>`_ on Step 1 and Step 2 for details.
Default assumptions
-------------------
For projects that follow standard best practices, **you should not require any customization beyond the above two steps**.
* Releases should be tagged as e.g. ``v0.1.0`` and deployed to a folder of the
same name. That is, a lower case letter ``v`` followed by a :PEP:`440`-compatible
version identifier.
* The ``master`` branch should be deployed to a folder ``master``, respectively
``main`` to a folder ``main`` for projects that `use "main" as the default branch name <https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/>`_.
* Any other branch for which documentation is to be deployed should go in a
folder matching the branch name.
Examples
--------
The following projects use Docs-Versions-Menu_, respectively `its predecessor Doctr-Versions-Menu <Doctr-Versions-Menu-PyPI_>`_:
* Krotov_
* caproto_
* pcds-ci-helpers_ (an example of shared Travis CI configurations using docs-versions-menu)
* lcls-twincat-general_ (among many other PLC projects at the LCLS)
.. _Docs-Versions-Menu: https://pypi.org/project/docs-versions-menu
.. _Doctr-Versions-Menu-PyPI: https://pypi.org/project/doctr-versions-menu
.. _Github: https://github.com/goerz/docs_versions_menu
.. _Github Actions: https://github.com/features/actions
.. _Github Pages: https://pages.github.com
.. _Sphinx: https://www.sphinx-doc.org/
.. _online: https://goerz.github.io/docs_versions_menu/
.. _Read the Docs: https://readthedocs.org
.. _Travis: https://travis-ci.org
.. _tox: https://tox.readthedocs.io
.. _Doctr: https://drdoctr.github.io
.. _Krotov: https://qucontrol.github.io/krotov/
.. _caproto: https://caproto.github.io/caproto/
.. _pcds-ci-helpers: https://github.com/pcdshub/pcds-ci-helpers/blob/d1bb15ace06cfd8fdda3f5ccad0981fcc59dfbe0/travis/shared_configs/doctr-upload.yml
.. _lcls-twincat-general: https://pcdshub.github.io/lcls-twincat-general/
.. _conda: https://docs.conda.io
.. _conda-forge: https://conda-forge.org
.. _conda-feedstock-instructions: https://github.com/conda-forge/docs-versions-menu-feedstock#installing-docs-versions-menu
.. _make: https://www.gnu.org/software/make/manual/make.html
.. _latex: https://www.latex-project.org
.. _workflow file: https://github.com/goerz/docs_versions_menu/blob/master/.github/workflows/docs.yml
=======
History
=======
0.5.2 (2023-04-19)
------------------
* Compatibility with ``packaging >= 22.0`` (`#27`_, `#32`_)
0.5.1 (2023-01-25)
------------------
* Pin ``packaging`` dependency to ``< 22.0`` (`#27`_, `#28`_)
0.5.0 (2022-11-17)
------------------
* Renamed project to ``docs-versions-menu`` (`#13`_)
* Changed: Removed support for a config file (`#9`_)
* Dropped support for Python 3.5 and Python 3.6
* Added support for Python 3.10 and 3.11
* Improvements to the workflow and documentation.
* Update of conda-feedstock_
.. _migration:
Migration from ``doctr-versions-menu``
--------------------------------------
The ``doctr-versions-menu`` package was renamed to ``docs-versions-menu`` to reflect that Travis_ and thus Doctr_ is `no longer a viable option to deploy documentation <TravisDemiseHN_>`_. Switching from ``doctr-versions-menu`` to ``docs-versions-menu`` requires the following steps:
* Consider switching from Travis_ to `Github Actions`_
* Update your Sphinx configuration (``conf.py``):
* Rename the ``doctr_versions_menu_conf`` dictionary of settings to ``docs_versions_menu_conf``.
* Change the name of the ``doctr_versions_menu`` extension in the ``extensions`` list to ``docs_versions_menu``.
* If using a custom ``doctr-versions-menu.js_t`` template, rename the file to ``docs-versions-menu.js_t``
* Update your continuous-integration setup:
* Replace the ``doctr-versions-menu`` package with ``docs-versions-menu`` in the project requirements (``setup.py``/``setup.cfg``)
* Replace the installation of the ``doctr-versions-menu`` package with ``docs-versions-menu`` in your CI script or environment files
* Replace calls to the ``doctr-versions-menu`` executable with calls to ``docs-versions-menu``
* If using environment variables for configuration, change the ``DOCTR_VERSIONS_MENU`` prefix to ``DOCS_VERSIONS_MENU``
* For any project using a ``doctr-versions-menu.conf`` file in the ``gh-pages`` root, set up equivalent ``DOCS_VERSIONS_MENU_*`` environment variables
To ease migration, the new ``docs-versions-menu`` will still process ``doctr_versions_menu_conf``, ``DOCTR_VERSIONS_MENU`` environment variables, and a ``doctr-versions-menu.js_t`` template, while emitting a warning. This limited backwards-compatibility may be removed in later versions.
0.4.1 (2021-03-18)
------------------
Note: this release was under the project name `doctr-versions-menu`_.
* Fixed: The ``doctr-versions-menu`` exectuable no longer fails when run outside of a git repository (`#15`_, thanks to `Alexander Blech <@ablech_>`_)
* Fixed: Custom ``doctr-versions-menu.js_t`` template were being ignored (`#18`_)
0.4.0 (2020-12-14)
------------------
Note: this release was under the project name `doctr-versions-menu`_.
* Added: The label in the top left corner of the version menu can now be configured in ``conf.py`` (setting ``menu_title``).
* Added: ``--default-branch`` option, ``<default-branch>`` group for folder specifications, and ``default-branch`` field in ``versions.json`` (`#12`_)
* Changed: The default ``--versions`` now uses ``<default-branch>``, automatically picking up on either "master" or "main" as the default branch (`#12`_)
* Changed: The default template for ``index.html`` now automatically forwards to the default-branch (based on the ``--default-branch`` option, instead of just "master"), or the first available branch if there is no released version (`#12`_)
This release addresses two major compatibility issues:
1. Both `git <GitMainDefaultBranch_>`_ and `Github <GithubMainDefaultBranch_>`_ have recently switched the name of the default branch from "master" to "main". This release adds support for new projects using "main" as their default branch.
2. As of December 2020, Travis CI has `stopped their support for open source <TravisDemiseHN_>`_. Consequently, Doctr_ can no longer be used to deploy documentation at no cost. This release adds rudimentary support for deploying the documenation with `Github Actions`_ instead of Doctr, see `Deployment with Github Actions <https://goerz.github.io/docs_versions_menu/v0.4.0/command.html#deployment-with-github-actions>`_.
0.3.0 (2020-08-03)
------------------
Note: this release was under the project name `doctr-versions-menu`_.
* Added: ``--no-downloads-file`` option, ``downloads_file = False`` in config. (`#4`_, thanks to `Tyler Pennebaker <@ZryletTC_>`_)
* Fixed: ``versions.py`` on ``gh-pages`` branch was not being committed (`#5`_)
* Fixed: Compatibility with any ``pyparsing`` version ``>= 2.0.2`` (`#8`_, thanks to `Hugo Slepicka <@hhslepicka_>`_)
* Added: The ``doctr-versions-menu`` executable can now be configured through environment variables. This allows to keep configuration on the source branch, in the ``.travis.yml`` file (`#6`_, thanks to `Tyler Pennebaker <@ZryletTC_>`_)
* The Doctr Versions Menu package can now be installed via `conda <conda-feedstock_>`_ (thanks to `Hugo Slepicka <@hhslepicka_>`_)
0.2.0 (2020-03-14)
------------------
Note: this release was under the project name `doctr-versions-menu`_.
* Added: ``--versions`` option for customizing which folders appear in the versions menu and in which order.
* Added: ``--label`` option for customizing the labels appearing the versions menu
* Added: ``--warning`` option for customizing on which folders specific warnings are displayed
* Added: ``--latest`` option for configuring which folder is the "latest stable release"
* Added: Write a script ``versions.py`` to the root of the ``gh-pages`` branch (``--write-versions-py`` option)
* Changed: unreleased and pre-released versions now show different warnings by default
* Changed: ``index.html`` template is now rendered with full ``version_data``
* Changed: development/pre-release versions now longer have the "dev" suffix in the versions menu by default
* Changed: The versions menu now uses the same ordering of versions as Read-the-Docs, by default: the folders are ordered from most current to least current.
* Changed: internal format of ``versions.json``
* Removed: ``--default-branch`` option. This is replaced by the new ``--latest`` option and enhanced template rendering of the ``index.html``
* Removed: ``--suffix-unreleased`` option. This can now be achieved via the ``--label`` option
This is a major release that breaks backwards compatibility.
Specifically, due to the changes in ``versions.json``, when upgrading from older versions, it
may be necessary to replace ``doctr-versions-menu.js`` files in existing
folders in a project's ``gh-pages`` branch.
0.1.0 (2020-01-11)
------------------
* Initial release of `doctr-versions-menu`_.
.. _doctr-versions-menu: https://pypi.org/project/doctr-versions-menu/
.. _GithubMainDefaultBranch: https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/
.. _GitMainDefaultBranch: https://github.blog/2020-07-27-highlights-from-git-2-28/#introducing-init-defaultbranch
.. _Travis: https://travis-ci.org
.. _TravisDemiseHN: https://news.ycombinator.com/item?id=25338983
.. _Doctr: https://drdoctr.github.io
.. _Github Actions: https://github.com/features/actions
.. _@ZryletTC: https://github.com/ZryletTC
.. _@hhslepicka: https://github.com/hhslepicka
.. _@ablech: https://github.com/ablech/
.. _#4: https://github.com/goerz/docs_versions_menu/issues/4
.. _#5: https://github.com/goerz/docs_versions_menu/issues/5
.. _#6: https://github.com/goerz/docs_versions_menu/issues/6
.. _#8: https://github.com/goerz/docs_versions_menu/issues/8
.. _#9: https://github.com/goerz/docs_versions_menu/issues/9
.. _#12: https://github.com/goerz/docs_versions_menu/issues/12
.. _#13: https://github.com/goerz/docs_versions_menu/issues/13
.. _#15: https://github.com/goerz/docs_versions_menu/issues/15
.. _#18: https://github.com/goerz/docs_versions_menu/issues/18
.. _#27: https://github.com/goerz/docs_versions_menu/issues/27
.. _#28: https://github.com/goerz/docs_versions_menu/issues/28
.. _#32: https://github.com/goerz/docs_versions_menu/issues/32
.. _conda-feedstock: https://github.com/conda-forge/docs-versions-menu-feedstock#readme
Raw data
{
"_id": null,
"home_page": "https://github.com/goerz/docs_versions_menu",
"name": "docs-versions-menu",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Doctr,Sphinx,Github",
"author": "Michael Goerz",
"author_email": "mail@michaelgoerz.net",
"download_url": "https://files.pythonhosted.org/packages/9e/b7/33bb6d00593ce0a7df5d4b13871b798d1cc8fd798933f036b058568dbe2d/docs_versions_menu-0.5.2.tar.gz",
"platform": null,
"description": "==================\nDocs-Versions-Menu\n==================\n\n.. image:: https://img.shields.io/badge/goerz-docs__versions__menu-blue.svg?logo=github\n :alt: Source code on Github\n :target: https://github.com/goerz/docs_versions_menu\n\n.. image:: https://img.shields.io/badge/docs-gh--pages-blue.svg\n :alt: Documentation\n :target: https://goerz.github.io/docs_versions_menu/\n\n.. image:: https://img.shields.io/pypi/v/docs_versions_menu.svg\n :alt: docs-versions-menu on the Python Package Index\n :target: https://pypi.org/project/docs-versions-menu\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/docs-versions-menu.svg\n :alt: docs-versions-menu on conda-forge\n :target: https://anaconda.org/conda-forge/docs-versions-menu\n\n.. image:: https://github.com/goerz/docs_versions_menu/workflows/Docs/badge.svg?branch=master\n :alt: Docs\n :target: https://github.com/goerz/docs_versions_menu/actions?query=workflow%3ADocs\n\n.. image:: https://github.com/goerz/docs_versions_menu/workflows/PyPI/badge.svg?branch=master\n :alt: PyPI\n :target: https://github.com/goerz/docs_versions_menu/actions?query=workflow%3APyPI\n\n.. image:: https://github.com/goerz/docs_versions_menu/workflows/Tests/badge.svg?branch=master\n :alt: Tests\n :target: https://github.com/goerz/docs_versions_menu/actions?query=workflow%3ATests\n\n.. image:: https://codecov.io/gh/goerz/docs_versions_menu/branch/master/graph/badge.svg\n :alt: Codecov\n :target: https://codecov.io/gh/goerz/docs_versions_menu\n\n.. image:: https://img.shields.io/badge/License-MIT-green.svg\n :alt: MIT License\n :target: https://opensource.org/licenses/MIT\n\nA versions-menu for Sphinx_-based documentation.\n\nHistorically, many open source projects have hosted their documentation on `Read the Docs`_ (RTD). However, RTD has a fixed `build process <https://docs.readthedocs.io/en/stable/builds.html>`_ that is essentially limited to just running Sphinx_. Moreover, RTD will inject advertisements into your documentation.\n\nA more flexible approach is to build the documentation with continuous integration (e.g., `Github Actions`_) and to deploy the result to `Github Pages`_ or any other static site hosting. There are no restrictions on the build process: it may involve make_, tox_, latex_, or any number of custom scripts to augment Sphinx_.\n\nThe one difficulty that comes with self-hosting project documentation is that out of the box, there is no support for showing multiple releases or branches of the project. This project aims to remedy this. It **provides a Sphinx extension and a command-line tool that work together to generate a dynamic versions-menu similar to that on RTD pages.**\n\n.. image:: https://raw.githubusercontent.com/goerz/docs_versions_menu/master/docs/_static/docs-versions-menu-screenshot.png\n :alt: Docs-Versions-Menu Screenshot\n\nThe different \"Versions\" derive from the folder structure of the hosted documentation, e.g., for `Github Pages`_, the folders in the root of the ``gh-pages`` branch. The ``docs-versions-menu`` command-line tool, running on the ``gh-pages`` branch or on the server hosting the documentation, collects the available versions based on the folders it sees.\n\nThe ``docs_versions_menu`` Sphinx extension, running during the Sphinx build process, adds Javascript to the documentation that will inject a menu to switch between the found versions. It can also show warnings for outdated or unreleased versions.\n\nSee the Docs-Versions-Menu documentation itself for a `live example <online_>`_.\n\nDevelopment of Docs-Versions-Menu happens on `Github`_.\nYou can read the full documentation online_.\n\nInstallation\n------------\n\nTo install the latest released version of ``docs-versions-menu``, run:\n\n.. code-block:: shell\n\n pip install docs-versions-menu\n\nOr, to install the latest development version of ``docs-versions-menu`` from `Github`_:\n\n.. code-block:: shell\n\n pip install git+https://github.com/goerz/docs_versions_menu.git@master#egg=docs_versions_menu\n\n\nThe ``docs-versions-menu`` package can also be installed through conda_, using\nthe conda-forge_ channel. See the `instructions in the Docs-Versions-Menu\nFeedstock <conda-feedstock-instructions_>`_.\n\nUsage\n-----\n\nShowing a versions-menu in your documentation requires two steps:\n\n1. Add ``'docs_versions_menu'`` to the list of extensions in your Sphinx ``conf.py``.\n\n This adds Javascript to your rendered documentation that displays a dynamic versions-menu based on information in a ``versions.json`` file it expects to find in the webroot of the hosted documentation, e.g. the root of the ``gh-pages`` branch.\n\n\n2. Set up the deployment of the documentation such that it runs the ``docs-versions-menu`` command in the webroot.\n\n The command creates the file ``versions.json`` that step 1 depends on by analyzing the folders it finds in the webroot.\n\n How to invoke ``docs-versions-menu`` depends on the specifics of how the documentation is deployed:\n\n * For `Github Actions`_ deploying to `Github Pages`_, check out the ``gh-pages`` branch, run ``docs-versions-menu``, and commit and push the resulting files.\n See the `workflow file`_ for Docs-Versions-Menu's documentation.\n\n * For Travis_ deploying to `Github Pages`_ with Doctr_, tell ``doctr deploy`` to invoke the ``docs-versions-menu`` command:\n\n .. code-block:: shell\n\n doctr deploy --command=docs-versions-menu --no-require-master --build-tags \"$DEPLOY_DIR\"\n\n * For deployments to a static web host, use ``ssh`` to run the ``docs-versions-menu`` command on the server\n\n\nSee the `full documentation <online_>`_ on Step 1 and Step 2 for details.\n\n\nDefault assumptions\n-------------------\n\nFor projects that follow standard best practices, **you should not require any customization beyond the above two steps**.\n\n* Releases should be tagged as e.g. ``v0.1.0`` and deployed to a folder of the\n same name. That is, a lower case letter ``v`` followed by a :PEP:`440`-compatible\n version identifier.\n* The ``master`` branch should be deployed to a folder ``master``, respectively\n ``main`` to a folder ``main`` for projects that `use \"main\" as the default branch name <https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/>`_.\n* Any other branch for which documentation is to be deployed should go in a\n folder matching the branch name.\n\n\nExamples\n--------\n\nThe following projects use Docs-Versions-Menu_, respectively `its predecessor Doctr-Versions-Menu <Doctr-Versions-Menu-PyPI_>`_:\n\n* Krotov_\n* caproto_\n* pcds-ci-helpers_ (an example of shared Travis CI configurations using docs-versions-menu)\n* lcls-twincat-general_ (among many other PLC projects at the LCLS)\n\n.. _Docs-Versions-Menu: https://pypi.org/project/docs-versions-menu\n.. _Doctr-Versions-Menu-PyPI: https://pypi.org/project/doctr-versions-menu\n.. _Github: https://github.com/goerz/docs_versions_menu\n.. _Github Actions: https://github.com/features/actions\n.. _Github Pages: https://pages.github.com\n.. _Sphinx: https://www.sphinx-doc.org/\n.. _online: https://goerz.github.io/docs_versions_menu/\n.. _Read the Docs: https://readthedocs.org\n.. _Travis: https://travis-ci.org\n.. _tox: https://tox.readthedocs.io\n.. _Doctr: https://drdoctr.github.io\n.. _Krotov: https://qucontrol.github.io/krotov/\n.. _caproto: https://caproto.github.io/caproto/\n.. _pcds-ci-helpers: https://github.com/pcdshub/pcds-ci-helpers/blob/d1bb15ace06cfd8fdda3f5ccad0981fcc59dfbe0/travis/shared_configs/doctr-upload.yml\n.. _lcls-twincat-general: https://pcdshub.github.io/lcls-twincat-general/\n.. _conda: https://docs.conda.io\n.. _conda-forge: https://conda-forge.org\n.. _conda-feedstock-instructions: https://github.com/conda-forge/docs-versions-menu-feedstock#installing-docs-versions-menu\n.. _make: https://www.gnu.org/software/make/manual/make.html\n.. _latex: https://www.latex-project.org\n.. _workflow file: https://github.com/goerz/docs_versions_menu/blob/master/.github/workflows/docs.yml\n\n\n=======\nHistory\n=======\n\n0.5.2 (2023-04-19)\n------------------\n\n* Compatibility with ``packaging >= 22.0`` (`#27`_, `#32`_)\n\n\n0.5.1 (2023-01-25)\n------------------\n\n* Pin ``packaging`` dependency to ``< 22.0`` (`#27`_, `#28`_)\n\n\n0.5.0 (2022-11-17)\n------------------\n\n* Renamed project to ``docs-versions-menu`` (`#13`_)\n* Changed: Removed support for a config file (`#9`_)\n* Dropped support for Python 3.5 and Python 3.6\n* Added support for Python 3.10 and 3.11\n* Improvements to the workflow and documentation.\n* Update of conda-feedstock_\n\n.. _migration:\n\n\nMigration from ``doctr-versions-menu``\n--------------------------------------\n\nThe ``doctr-versions-menu`` package was renamed to ``docs-versions-menu`` to reflect that Travis_ and thus Doctr_ is `no longer a viable option to deploy documentation <TravisDemiseHN_>`_. Switching from ``doctr-versions-menu`` to ``docs-versions-menu`` requires the following steps:\n\n* Consider switching from Travis_ to `Github Actions`_\n* Update your Sphinx configuration (``conf.py``):\n * Rename the ``doctr_versions_menu_conf`` dictionary of settings to ``docs_versions_menu_conf``.\n * Change the name of the ``doctr_versions_menu`` extension in the ``extensions`` list to ``docs_versions_menu``.\n * If using a custom ``doctr-versions-menu.js_t`` template, rename the file to ``docs-versions-menu.js_t``\n* Update your continuous-integration setup:\n * Replace the ``doctr-versions-menu`` package with ``docs-versions-menu`` in the project requirements (``setup.py``/``setup.cfg``)\n * Replace the installation of the ``doctr-versions-menu`` package with ``docs-versions-menu`` in your CI script or environment files\n * Replace calls to the ``doctr-versions-menu`` executable with calls to ``docs-versions-menu``\n * If using environment variables for configuration, change the ``DOCTR_VERSIONS_MENU`` prefix to ``DOCS_VERSIONS_MENU``\n* For any project using a ``doctr-versions-menu.conf`` file in the ``gh-pages`` root, set up equivalent ``DOCS_VERSIONS_MENU_*`` environment variables\n\nTo ease migration, the new ``docs-versions-menu`` will still process ``doctr_versions_menu_conf``, ``DOCTR_VERSIONS_MENU`` environment variables, and a ``doctr-versions-menu.js_t`` template, while emitting a warning. This limited backwards-compatibility may be removed in later versions.\n\n\n0.4.1 (2021-03-18)\n------------------\n\nNote: this release was under the project name `doctr-versions-menu`_.\n\n* Fixed: The ``doctr-versions-menu`` exectuable no longer fails when run outside of a git repository (`#15`_, thanks to `Alexander Blech <@ablech_>`_)\n* Fixed: Custom ``doctr-versions-menu.js_t`` template were being ignored (`#18`_)\n\n0.4.0 (2020-12-14)\n------------------\n\nNote: this release was under the project name `doctr-versions-menu`_.\n\n* Added: The label in the top left corner of the version menu can now be configured in ``conf.py`` (setting ``menu_title``).\n* Added: ``--default-branch`` option, ``<default-branch>`` group for folder specifications, and ``default-branch`` field in ``versions.json`` (`#12`_)\n* Changed: The default ``--versions`` now uses ``<default-branch>``, automatically picking up on either \"master\" or \"main\" as the default branch (`#12`_)\n* Changed: The default template for ``index.html`` now automatically forwards to the default-branch (based on the ``--default-branch`` option, instead of just \"master\"), or the first available branch if there is no released version (`#12`_)\n\nThis release addresses two major compatibility issues:\n\n1. Both `git <GitMainDefaultBranch_>`_ and `Github <GithubMainDefaultBranch_>`_ have recently switched the name of the default branch from \"master\" to \"main\". This release adds support for new projects using \"main\" as their default branch.\n2. As of December 2020, Travis CI has `stopped their support for open source <TravisDemiseHN_>`_. Consequently, Doctr_ can no longer be used to deploy documentation at no cost. This release adds rudimentary support for deploying the documenation with `Github Actions`_ instead of Doctr, see `Deployment with Github Actions <https://goerz.github.io/docs_versions_menu/v0.4.0/command.html#deployment-with-github-actions>`_.\n\n\n0.3.0 (2020-08-03)\n------------------\n\nNote: this release was under the project name `doctr-versions-menu`_.\n\n* Added: ``--no-downloads-file`` option, ``downloads_file = False`` in config. (`#4`_, thanks to `Tyler Pennebaker <@ZryletTC_>`_)\n* Fixed: ``versions.py`` on ``gh-pages`` branch was not being committed (`#5`_)\n* Fixed: Compatibility with any ``pyparsing`` version ``>= 2.0.2`` (`#8`_, thanks to `Hugo Slepicka <@hhslepicka_>`_)\n* Added: The ``doctr-versions-menu`` executable can now be configured through environment variables. This allows to keep configuration on the source branch, in the ``.travis.yml`` file (`#6`_, thanks to `Tyler Pennebaker <@ZryletTC_>`_)\n* The Doctr Versions Menu package can now be installed via `conda <conda-feedstock_>`_ (thanks to `Hugo Slepicka <@hhslepicka_>`_)\n\n\n0.2.0 (2020-03-14)\n------------------\n\nNote: this release was under the project name `doctr-versions-menu`_.\n\n* Added: ``--versions`` option for customizing which folders appear in the versions menu and in which order.\n* Added: ``--label`` option for customizing the labels appearing the versions menu\n* Added: ``--warning`` option for customizing on which folders specific warnings are displayed\n* Added: ``--latest`` option for configuring which folder is the \"latest stable release\"\n* Added: Write a script ``versions.py`` to the root of the ``gh-pages`` branch (``--write-versions-py`` option)\n* Changed: unreleased and pre-released versions now show different warnings by default\n* Changed: ``index.html`` template is now rendered with full ``version_data``\n* Changed: development/pre-release versions now longer have the \"dev\" suffix in the versions menu by default\n* Changed: The versions menu now uses the same ordering of versions as Read-the-Docs, by default: the folders are ordered from most current to least current.\n* Changed: internal format of ``versions.json``\n* Removed: ``--default-branch`` option. This is replaced by the new ``--latest`` option and enhanced template rendering of the ``index.html``\n* Removed: ``--suffix-unreleased`` option. This can now be achieved via the ``--label`` option\n\nThis is a major release that breaks backwards compatibility.\n\nSpecifically, due to the changes in ``versions.json``, when upgrading from older versions, it\nmay be necessary to replace ``doctr-versions-menu.js`` files in existing\nfolders in a project's ``gh-pages`` branch.\n\n\n0.1.0 (2020-01-11)\n------------------\n\n* Initial release of `doctr-versions-menu`_.\n\n.. _doctr-versions-menu: https://pypi.org/project/doctr-versions-menu/\n.. _GithubMainDefaultBranch: https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/\n.. _GitMainDefaultBranch: https://github.blog/2020-07-27-highlights-from-git-2-28/#introducing-init-defaultbranch\n.. _Travis: https://travis-ci.org\n.. _TravisDemiseHN: https://news.ycombinator.com/item?id=25338983\n.. _Doctr: https://drdoctr.github.io\n.. _Github Actions: https://github.com/features/actions\n.. _@ZryletTC: https://github.com/ZryletTC\n.. _@hhslepicka: https://github.com/hhslepicka\n.. _@ablech: https://github.com/ablech/\n.. _#4: https://github.com/goerz/docs_versions_menu/issues/4\n.. _#5: https://github.com/goerz/docs_versions_menu/issues/5\n.. _#6: https://github.com/goerz/docs_versions_menu/issues/6\n.. _#8: https://github.com/goerz/docs_versions_menu/issues/8\n.. _#9: https://github.com/goerz/docs_versions_menu/issues/9\n.. _#12: https://github.com/goerz/docs_versions_menu/issues/12\n.. _#13: https://github.com/goerz/docs_versions_menu/issues/13\n.. _#15: https://github.com/goerz/docs_versions_menu/issues/15\n.. _#18: https://github.com/goerz/docs_versions_menu/issues/18\n.. _#27: https://github.com/goerz/docs_versions_menu/issues/27\n.. _#28: https://github.com/goerz/docs_versions_menu/issues/28\n.. _#32: https://github.com/goerz/docs_versions_menu/issues/32\n.. _conda-feedstock: https://github.com/conda-forge/docs-versions-menu-feedstock#readme\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "A versions menu for Sphinx-based documentation",
"version": "0.5.2",
"split_keywords": [
"doctr",
"sphinx",
"github"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "232389993b2e9895add5e76a3f38ceb3c06dc2f1d0733937568085a36a56b21b",
"md5": "6e6217ae247160230108b593b9c922c1",
"sha256": "8e331e2e9b2c9d3a7b2a7c8325a7e7ed7070b144cd3ef0f701172468af7e3cdf"
},
"downloads": -1,
"filename": "docs_versions_menu-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e6217ae247160230108b593b9c922c1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 533159,
"upload_time": "2023-04-20T03:41:45",
"upload_time_iso_8601": "2023-04-20T03:41:45.019333Z",
"url": "https://files.pythonhosted.org/packages/23/23/89993b2e9895add5e76a3f38ceb3c06dc2f1d0733937568085a36a56b21b/docs_versions_menu-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9eb733bb6d00593ce0a7df5d4b13871b798d1cc8fd798933f036b058568dbe2d",
"md5": "48d8f3649d5d40478ae0e37fb4251855",
"sha256": "8c6eae5836fb63e4f9700387385c5074dac8187609538422dab5fa39de110a73"
},
"downloads": -1,
"filename": "docs_versions_menu-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "48d8f3649d5d40478ae0e37fb4251855",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 782903,
"upload_time": "2023-04-20T03:41:47",
"upload_time_iso_8601": "2023-04-20T03:41:47.030699Z",
"url": "https://files.pythonhosted.org/packages/9e/b7/33bb6d00593ce0a7df5d4b13871b798d1cc8fd798933f036b058568dbe2d/docs_versions_menu-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-20 03:41:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "goerz",
"github_project": "docs_versions_menu",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "docs-versions-menu"
}
JSON
