Document deployment on Github Actions

HISTORY.rst

@@ -10,6 +10,11 @@ History
 * 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 releases 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/doctr_versions_menu/master/command.html#deployment-with-github-actions>`_.
+
 
 0.3.0 (2020-08-03)
 ------------------
@@ -50,6 +55,11 @@ folders in a project's ``gh-pages`` branch.
 * Initial release
 
 
+.. _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
+.. _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
 .. _#4: https://github.com/goerz/doctr_versions_menu/issues/4

README.rst

@@ -52,6 +52,8 @@ 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_.
 
+⚠️ **As of December 2020, Travis no longer provides free services to open source projects.** See `Deployment with Github Actions <https://goerz.github.io/doctr_versions_menu/master/command.html#deployment-with-github-actions>`_ for a workaround.
+
 
 Installation
 ------------

docs/command.rst

@@ -43,6 +43,38 @@ The main purpose of the ``doctr-versions-menu`` command is to generate the
 ``versions.json`` file that the :ref:`Sphinx extension <sphinx_extension>`
 relies on, in the root of the ``gh-pages`` branch.
 
+.. _deployment-with-github-actions:
+
+Deployment with Github Actions
+------------------------------
+
+As of December 2020, Travis ended their support for open source software. Thus, it is no longer possible to use Doctr as originally intended and as described throughout this documentation. The recommended alternative for all continous integration (including building documentation) is to use `Github Actions`_. Doctr `may add support for Github Actions in the future <https://github.com/drdoctr/doctr/issues/351>`_. In the meantime, for basic use cases (deploying the documentation to the ``gh-pages`` branch of the same repository), it is quite straightforward to implement the deployment "by hand". A possible workflow is the following:
+
+* Build the documentation, zip the resulting html and upload it as an artifact
+* In a second job within the same workflow:
+
+  - Check out the ``gh-pages`` branch
+  - Download the artifact generated by the first job and unpack it to a temporary location
+  - Synchronize the unpacked html files with the appropriate subfolder within the ``gh-pages`` branch
+  - Run the ``doctr-versions-menu`` command
+  - Commit and push the changes.
+
+What makes this easy within Github Actions, is that the action is automatically authenticated to upload/download artifacts and to have push-access to the underlying repository. Thus, Doctr's main feature of managing the deploy key for Travis becomes obsolete.
+
+`An example workflow file illustrates this in more detail. <https://github.com/goerz-testing/cython-package-example/blob/e60098f7d38c4a7a8d2ec73fe6e96016f2b47fa5/.github/workflows/docs.yml>`_
+
+If you are not using Travis/Doctr, you probably also want to :ref:`change the menu title <sphinx_ext_customization>`, by putting e.g.
+
+.. code-block:: python
+
+    doctr_versions_menu_conf = {
+        'menu_title': 'Docs'  # instead of 'Doctr'
+    }
+
+in your  ``conf.py`` file.
+
+.. _Github Actions: https://github.com/features/actions
+
 
 .. _command-line-options:
 

docs/index.rst

@@ -32,6 +32,12 @@ Welcome to the Doctr Versions Menu documentation
 
 Sphinx_ extension and command to add a versions menu to Doctr_-deployed documentation.
 
+.. warning::
+
+    As of December 2020, Travis no longer provides free services to open source
+    projects. See :ref:`deployment-with-github-actions` for a workaround.
+
+
 **Table of Contents**
 
 .. toctree::

docs/sphinx_extension.rst

@@ -70,7 +70,7 @@ file ``doctr-versions-menu.js_t`` in a folder listed in your
 
 This template will be rendered to produce ``doctr-versions-menu.js``
 using values from a dictionary ``doctr_versions_menu_conf`` in your Sphinx
-``docs.conf`` file. Values in this dictionary may overwrite the following
+``conf.py`` file. Values in this dictionary may overwrite the following
 defaults used in the `default template`_:
 
 * ``json_file`` (str): The local (absolute) path to the json file that contains version information. Defaults to ``/<project>/versions.json`` with ``<project>`` dynamically set based on the current Github Pages URL (``https://<username>.github.io/<project>/<version>/...``)