Metadata-Version: 2.1
Name: doctr-versions-menu
Version: 0.3.0
Summary: Sphinx extension and command to add a versions menu to Doctr-deployed documentation
Home-page: https://github.com/goerz/doctr_versions_menu
Author: Michael Goerz
Author-email: mail@michaelgoerz.net
License: MIT license
Keywords: Doctr,Sphinx,Github
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Environment :: Plugins
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Operating System :: OS Independent
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
Requires-Dist: click (>=6.7)
Requires-Dist: configobj (>=5.0.6)
Requires-Dist: doctr
Requires-Dist: packaging
Requires-Dist: pyparsing (>=2.0.2)
Requires-Dist: setuptools
Requires-Dist: sphinx
Provides-Extra: dev
Requires-Dist: coverage (<5.0) ; extra == 'dev'
Requires-Dist: coveralls ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: gitpython ; extra == 'dev'
Requires-Dist: ipython ; extra == 'dev'
Requires-Dist: isort ; extra == 'dev'
Requires-Dist: pdbpp ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: pylint ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pytest-xdist ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'dev'
Requires-Dist: sphinx-autobuild ; extra == 'dev'
Requires-Dist: sphinx-autodoc-typehints ; extra == 'dev'
Requires-Dist: sphinx-copybutton ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme ; extra == 'dev'
Requires-Dist: travis-encrypt ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: wheel ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'

===================
Doctr Versions Menu
===================

.. image:: https://img.shields.io/badge/github-goerz/doctr__versions__menu-blue.svg
   :alt: Source code on Github
   :target: https://github.com/goerz/doctr_versions_menu

.. image:: https://img.shields.io/badge/docs-doctr-blue.svg
   :alt: Documentation
   :target: https://goerz.github.io/doctr_versions_menu/

.. image:: https://img.shields.io/pypi/v/doctr_versions_menu.svg
   :alt: doctr-versions-menu on the Python Package Index
   :target: https://pypi.python.org/pypi/doctr_versions_menu

.. image:: https://img.shields.io/travis/goerz/doctr_versions_menu.svg
   :alt: Travis Continuous Integration
   :target: https://travis-ci.org/goerz/doctr_versions_menu

.. image:: https://ci.appveyor.com/api/projects/status/tg95oketoqa94alp/branch/master?svg=true
   :alt: AppVeyor Continuous Integration
   :target: https://ci.appveyor.com/project/goerz/doctr-versions-menu

.. image:: https://img.shields.io/coveralls/github/goerz/doctr_versions_menu/master.svg
   :alt: Coveralls
   :target: https://coveralls.io/github/goerz/doctr_versions_menu?branch=master

.. image:: https://img.shields.io/badge/License-MIT-green.svg
   :alt: MIT License
   :target: https://opensource.org/licenses/MIT

Sphinx_ extension and command to add a versions menu to Doctr_-deployed documentation.

Doctr_ is a tool that deploys Sphinx_ documentation from `Travis CI <Travis_>`_
to `Github Pages`_. It is an alternative to the popular `Read the Docs`_ (RTD).
Compared to RTD, Doctr gives full control over the documentation build process.
However, Doctr out of the box does not support documentation for multiple
versions of a package at the same time (unlike RTD).

The ``doctr-versions-menu`` package 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/doctr_versions_menu/master/docs/_static/doctr-versions-menu-screenshot.png
  :alt: Doctr Versions Menu Screenshot

It also injects warnings for outdated or unreleased versions.

See the ``doctr-versions-menu`` documentation itself for a `live example <online_>`_.

Development of Doctr Versions Menu happens on `Github`_.
You can read the full documentation online_.


Installation
------------

To install the latest released version of ``doctr-versions-menu``, run:

.. code-block:: shell

    pip install doctr-versions-menu

Or, to install the latest development version of ``doctr-versions-menu`` from `Github`_:

.. code-block:: shell

    pip install git+https://github.com/goerz/doctr_versions_menu.git@master#egg=doctr_versions_menu


The ``doctr-versions-menu`` package can also be installed through conda_, using
the conda-forge_ channel. See the `instructions in the Doctr Versions Menu
Feedstock <conda-feedstock-instructions_>`_.

In practice, you probably only have to install the ``doctr-versions-menu``
package on Travis_, for generating and deploying the documentation; or, e.g.,
in a local tox_ environment for generating documentation locally during
development.


Usage
-----

Showing a versions menu in your documentation requires two steps:

1.  Add ``'doctr_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 root for your ``gh-pages`` branch.


2.  Call the ``doctr-versions-menu`` command as part of ``doctr deploy`` (in ``.travis.yml``).

    For example,

    .. code-block:: shell

        doctr deploy --command=doctr-versions-menu --no-require-master --build-tags "$DEPLOY_DIR"

    This causes ``doctr-versions-menu`` to be executed in the root of the ``gh-pages`` branch. The script examines the folders that exist there, and generates the ``versions.json`` file that step 1 relies on.

See the `full documentation <online_>`_ on Step 1 and Step 2 for details. However, for projects that follow normal best practices, **you should not require any customization beyond the above two steps**.


Examples
--------

The following projects use ``doctr-versions-menu``:

* Krotov_


.. _Github: https://github.com/goerz/doctr_versions_menu
.. _Github pages: https://pages.github.com
.. _Doctr: https://drdoctr.github.io
.. _Sphinx: https://www.sphinx-doc.org/
.. _online: https://goerz.github.io/doctr_versions_menu/
.. _Read the Docs: https://readthedocs.org
.. _Travis: https://travis-ci.org
.. _tox: https://tox.readthedocs.io
.. _Krotov: https://qucontrol.github.io/krotov/
.. _conda: https://docs.conda.io
.. _conda-forge: https://conda-forge.org
.. _conda-feedstock-instructions: https://github.com/conda-forge/doctr-versions-menu-feedstock#installing-doctr-versions-menu


=======
History
=======

0.3.0 (2020-08-03)
------------------

* 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)
------------------

* 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


.. _@ZryletTC: https://github.com/ZryletTC
.. _@hhslepicka: https://github.com/hhslepicka
.. _#4: https://github.com/goerz/doctr_versions_menu/issues/4
.. _#5: https://github.com/goerz/doctr_versions_menu/issues/5
.. _#6: https://github.com/goerz/doctr_versions_menu/issues/6
.. _#8: https://github.com/goerz/doctr_versions_menu/issues/8
.. _conda-feedstock: https://github.com/conda-forge/doctr-versions-menu-feedstock#readme


