April 2022 Update for Sphinx reStructuredText Technical Notes

Data Management DM Notifications
#1

We’ve released an update to our template for Sphinx/reStructuredText technical notes. The new template has two important benefits:

  1. Documenteer 0.6 (or latest) adoption. The new Sphinx conf.py file is much simpler than before and prevents a recursion error when rebuilding technical notes. The new version of Documenteer also tracks the latest version of Sphinx, which lets us use the latest versions of Sphinx extensions.
  2. We’ve simplified the GitHub Actions workflow and made it more maintainable through reusable workflows. The core workflow logic for building and deploying a technote is now maintained in lsst-sqre/rubin-sphinx-technote-workflows. As the workflow changes in the months and years ahead, we’ll now be able to roll out those changes to your technote without any action on your part as a technote author.

We plan to release an equivalent change for LaTeX technotes in the near future. Stay tuned for that announcement.

How to upgrade your Sphinx technote

Existing technotes will continue to build. However, you can opt into the new build system by making a few changes to your technical note repository.

If you’re unsure about what your technote repository should look like, refer to this example built from the template.

1. Make sure .travis.yml is deleted

We deprecated Travis CI usage a while back, but your older technote projects might still be using it. If you have a .travis.yml file in your technote’s repository, run:

git rm .travis.yml
git commit

You’ll also want to change the CI status badge at the top of your technote’s README, see the example README for guidance.

2. Update the requirements.txt file

Update the requirements.txt file (i.e., unpin documenteer):

documenteer[technote]

If your technote uses additional Sphinx extensions that aren’t included by default, you can add them to this pip requirements file.

3. Update the conf.py file

Update the conf.py Sphinx configuration file:

"""Sphinx configuration.

To learn more about the Sphinx configuration for technotes, and how to
customize it, see:

https://documenteer.lsst.io/technotes/configuration.html
"""

from documenteer.conf.technote import *  # noqa: F401, F403

If your technote has custom configurations, like intersphinx links or Sphinx extensions, append those configurations after the import. See the Documenteer documentation for how to do this.

4. Update the .github/workflows/ci.yaml file

Either create .github/workflows/ci.yaml if you haven’t already, or modify it with the sample below.

Update the testn-000 string with your technote’s lowercase handle, such as rtn-001, dmtn-001, or tstn-001, etc…

name: CI

'on': [push, pull_request, workflow_dispatch]

jobs:
  call-workflow:
    uses: lsst-sqre/rubin-sphinx-technote-workflows/.github/workflows/ci.yaml@v1
    with:
      handle: testn-000
    secrets:
      ltd_username: ${{ secrets.LTD_USERNAME }}
      ltd_password: ${{ secrets.LTD_PASSWORD }}

The secrets reference GitHub Actions secrets that should already exist in your GitHub organization; you shouldn’t need to change that section.

If your technote build requires additional software such as graphviz or pandoc, you can specify them with an apt_packages input:

name: CI

'on': [push, pull_request, workflow_dispatch]

jobs:
  call-workflow:
    uses: lsst-sqre/rubin-sphinx-technote-workflows/.github/workflows/ci.yaml@v1
    with:
      handle: testn-000
      apt_packages: "graphviz pandoc"
    secrets:
      ltd_username: ${{ secrets.LTD_USERNAME }}
      ltd_password: ${{ secrets.LTD_PASSWORD }}

For more documentation on this workflow, see lsst-sqre/rubin-sphinx-technote-workflows.

If you have any questions, feel free to reply to this topic or post in #dm-docs-support on the LSSTC Slack.

3 Likes