Merge pull request #207 from lsst-sqre/tickets/DM-42142

DM-42142: Update documentation and prepare for 1.0.0 release
lsst-sqre · Dec 17, 2023 · bea3adb · bea3adb
2 parents 7964d58 + a073187
commit bea3adb
Show file tree

Hide file tree

Showing 22 changed files with 425 additions and 160 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,21 +1,74 @@
 # Change Log
 
-## Unreleased
-
-- Add a new `documenteer.conf.technotebeta` configuration for [technote](https://technote.lsst.io)-based technotes.
-  These technotes are now themed with Rubin's modern branding.
-- Drop support for Python 3.7.
-- Drop support for Sphinx versions earlier than 5.
-- Temporarily pin pydata-sphinx-theme < 0.13 on account of a change in logo path checking (affects user guide projects).
-- Use [sphinxcontrib-jquery](https://github.com/sphinx-contrib/jquery/) to ensure jQuery is available for user guide and Pipelines documentation builds.
-- Add a new `sphinx.exclude` field to `documenteer.toml` to list files for exclusion from a documentation project.
-  More files and directories like `.venv` and `requirements.txt` are now excluded, as well.
-- New support for embedding OpenAPI documentation in a Redoc-generated subsite. The `documenteer.ext.openapi` extension can call a user-specified function to generate and install the OpenAPI specification the Sphinx source. For user guide projects, the `[project.openapi]` table in `documenteer.toml` can be used to configure both the `documenteer.ext.openapi` and `sphinxcontrib-redoc` extensions. [sphinxcontrib-redoc](https://sphinxcontrib-redoc.readthedocs.io/en/stable/) is installed and configured by default for all Rubin user guide projects (projects that use `documenteer.conf.guide`).
-- Pin pydantic < 2.0.
-- Pin Sphinx < 7.
-
 <!-- scriv-insert-here -->
 
+<a id='changelog-1.0.0'></a>
+## 1.0.0 (2023-12-17)
+
+### Backwards-incompatible changes
+
+- Documenteer now requires Python 3.11 or later.
+
+- Dependency changes:
+
+  - Pydantic 2.0 or later.
+  - Sphinx 7 and later (and docutils 0.20 and later)
+  - pydata-sphinx-theme < 0.13 on account of a change in logo path checking (affects user guide projects).
+
+- Dropped support for the original technote configuration for Documenteer < 1.0. The `documenteer.conf.technote` configuration now uses the modern platform build with [Technote](https://technote.lsst.io). See new features below for more details.
+
+- Dropped CLI commands:
+
+  - The `refresh-lsst-bib` CLI command is removed. Technotes now automatically vendor lsst-texmf's bib files and cache them using `documenteer.ext.githubbibcache`.
+  - The `build-stack-docs` CLI command is removed and replaced by the `stack-docs` and `package-docs` CLIs in Documenteer 0.3.0.
+
+- The `documenteer.conf.pipelines` and `documenteer.conf.pipelinespkg` configuration modules now derive from `documenteer.conf.guide`. In doing so, the Pipelines documentation configuration works the same as Rubin Guides, but with additional configuration for pipelines-specific Sphinx extensions and other configurations. With this change, the `lsst-sphinx-bootstrap-theme` is no longer used by Documenteer.
+
+- The `documenteer.sphinxext` module has been removed and the existing Sphinx extensions within it are now available from `documenteer.ext`. It's no longer possible to use `documenteer.sphinxext` to automatically load all Documenteer Sphinx extensions. Extensions need to now be added individually to the `extensions` configuration variable in `conf.py`. The migrated extension modules are:
+
+  - `documenteer.ext.bibtex`
+  - `documenteer.ext.jira`
+  - `documenteer.ext.lsstdocushare`
+  - `documenteer.ext.lssttasks`
+  - `documenteer.ext.mockcoderefs`
+  - `documenteer.ext.packagetoctree`
+
+### New features
+
+- All-new technote configuration for Rubin Observatory. Technotes are now built with a framework we created by the same name, [Technote](https://technote.lsst.io). The new technotes feature a responsive design, better on-page navigation, and overall cleaner design that matches Rubin Observatory's visual identity. For authors, technotes use a new configuration file, `technote.toml`, which replaces `metadata.yaml`. Technotes can also be written in Markdown (in addition to continuing reStructuredText support) thanks to [MyST Parser](https://myst-parser.readthedocs.io/en/latest/intro.html). Other key features:
+
+  - You can migrate your existing technote by running the `documenteer technote migrate` CLI command. The migration process is explained in detail at https://documenteer.lsst.io/technotes/migrate.html.
+
+  - Rubin technotes automatically use the bib files from https://github.com/lsst/lsst-texmf. In your text, use the `:cite:` directive with a bibkey from those bib files to cite a reference. Documenteer automatically retrieves the bib files from GitHub so you no longer need to maintain a copy in your repository.
+
+  - Rubin technotes include a richer metadata base than the original technote system. This will make it easier to cite technotes. Part of the richer metadata system is the authors table in `technote.toml` files. This author information is derived from, and synchronized with, the `authordb.yaml` file in [lsst/lsst-texmf](https://github.com/lsst/lsst-texmf). The `documenteer technote add-author` and `documenteer technote sync-authors` CLI commands can help you manage author information in your technote.
+
+  - The title for a technote is now derived from the top-level heading in the content itself.
+
+  - There is a new `abstract` directive for marking up a technote's abstract or summary. This replaces the use of a note for the summary. This summary abstract is used by the documentation crawler to build https://www.lsst.io.
+
+  - Technotes can now indicate their status with the `technote.status` field in `technote.toml`. For example, a technote can start out as a draft. You can also mark a technote as deprecated and link to superseding websites.
+
+  - The new technote configuration comes pre-loaded with extensions for making diagrams as code, including `sphinxcontrib-mermaid` and `sphinx-diagrams`.
+
+- Improvements for Rubin user guides (`documenteer.conf.guide`):
+
+  - Add `sphinx-jinja` to the Rubin guides configuration by default.
+  - Add `sphinx-rediraffe` to the Rubin guides configuration by default.
+  - Use [sphinxcontrib-jquery](https://github.com/sphinx-contrib/jquery/) to ensure jQuery is available for user guide and Pipelines documentation builds.
+  - New `sphinx.exclude` field to `documenteer.toml` to list files for exclusion from a documentation project. More files and directories like `.venv` and `requirements.txt` are now excluded, as well.
+  - New support for embedding OpenAPI documentation in a Redoc-generated subsite. The `documenteer.ext.openapi` extension can call a user-specified function to generate and install the OpenAPI specification the Sphinx source. For user guide projects, the `[project.openapi]` table in `documenteer.toml` can be used to configure both the `documenteer.ext.openapi` and `sphinxcontrib-redoc` extensions. [sphinxcontrib-redoc](https://sphinxcontrib-redoc.readthedocs.io/en/stable/) is installed and configured by default for all Rubin user guide projects (projects that use `documenteer.conf.guide`).
+
+- A new extension, `documenteer.ext.githubbibcache`, can fetch and locally cache BibTeX files from one or more public GitHub repositories. These bibfiles are automatically added to `sphinxcontrib-bibtex`'s `bibtex_files` configuration. This powers the technote's automatic use of bib files from the https://github.com/lsst/lsst-texmf repository.
+
+### Bug fixes
+
+- `Retry` is now imported directly from `urllib3` instead of the vendored version in requests.
+
+### Other changes
+
+- Adopted Scriv for maintaining the change log.
+
 ## 0.8.4 (2023-07-28)
 
 Fixes:

diff --git a/changelog.d/20230911_120423_jsick_DM_40684.md b/changelog.d/20230911_120423_jsick_DM_40684.md
diff --git a/changelog.d/20231012_194757_jsick_DM_41179.md b/changelog.d/20231012_194757_jsick_DM_41179.md
diff --git a/changelog.d/20231018_165310_jsick_DM_41214.md b/changelog.d/20231018_165310_jsick_DM_41214.md
diff --git a/changelog.d/20231024_170151_jsick_DM_41296.md b/changelog.d/20231024_170151_jsick_DM_41296.md
diff --git a/changelog.d/20231026_192111_jsick_DM_41370.md b/changelog.d/20231026_192111_jsick_DM_41370.md
diff --git a/changelog.d/20231128_164718_jsick_DM_41781.md b/changelog.d/20231128_164718_jsick_DM_41781.md
diff --git a/changelog.d/20231129_140754_jsick_DM_41905.md b/changelog.d/20231129_140754_jsick_DM_41905.md
diff --git a/changelog.d/20231201_154001_jsick_DM_41917.md b/changelog.d/20231201_154001_jsick_DM_41917.md
diff --git a/changelog.d/20231212_141904_jsick_DM_42023.md b/changelog.d/20231212_141904_jsick_DM_42023.md
diff --git a/docs/_rst_epilog.rst b/docs/_rst_epilog.rst
@@ -62,6 +62,9 @@
 .. _sphinx.ext.intersphinx: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 .. _`authordb.yaml`: https://github.com/lsst/lsst-texmf/blob/main/etc/authordb.yaml
 .. _pipx: https://pipx.pypa.io
+.. _`LSSTC Slack Workspace`: https://lsstc.slack.com
+
+.. |dmw-sqrbot| replace:: `direct message with @sqrbot-jr <https://slack.com/app_redirect?app=AF2U6ADV3&team=T06D204F2>`__
 
 .. Internal links
 

diff --git a/docs/technotes/author-metadata.rst b/docs/technotes/author-metadata.rst
@@ -0,0 +1,103 @@
+###########################
+Maintaining author metadata
+###########################
+
+The list of authors for a technote is maintained in the :file:`technote.toml` file.
+This page describes how to add and update author listings.
+
+The connection to authordb.yaml
+===============================
+
+The author metadata in a technote's :file:`technote.toml` file is *derived* from Rubin Observatory's author database, `authordb.yaml`_, located in the https://github.com/lsst/lsst-texmf repository.
+The ``internal_id`` field in :file:`technote.toml` points to the author's entry in `authordb.yaml`_.
+This is done so that team members are identified consistently across Rubin Observatory documents and publications.
+
+For example, an author with an ID of ``sickj`` is represented in :file:`technote.toml` as:
+
+.. code-block:: toml
+   :caption: technote.toml
+   :emphasize-lines: 3
+
+   [[technote.authors]]
+   name = {given = "Jonathan", family = "Sick"}
+   internal_id = "sickj"
+   orcid = "https://orcid.org/0000-0003-3001-676X"
+   [[technote.authors.affiliations]]
+   name = "Rubin Observatory Project Office"
+   internal_id = "RubinObs"
+   address = "950 N. Cherry Ave., Tucson, AZ 85719, USA"
+
+The corresponding entry in `authordb.yaml`_ is:
+
+.. code-block:: yaml
+   :caption: authordb.yaml in lsst/lsst-texmf
+   :emphasize-lines: 3
+
+   authors:
+     # [...]
+     sickj:
+       affil:
+       - RubinObs
+       altaffil: []
+       initials: Jonathan
+       name: Sick
+       orcid: 0000-0003-3001-676X
+
+The highlighted lines, above, show the author ID that connects these metadata sets.
+
+A consequence of this connection is that all technote authors must have an entry in `authordb.yaml`_.
+You can add and update entries by submitting a pull request to the https://github.com/lsst/lsst-texmf repository.
+
+Adding a new author
+===================
+
+Given an author ID from `authordb.yaml`_, you can add that author to the technote's metadata by running the :command:`make add-author` command:
+
+.. prompt:: bash
+
+   make add-author
+
+That command prompts you for the author ID, and then appends the author to the end of the author listing in :file:`technote.toml` (existing authors are updated in place).
+
+Authors are represented in :file:`technote.toml` as as individual tables under the ``technote.authors`` *array of tables*.
+A technote with Sick as the first author and Economou as the second author would look like:
+
+.. code-block:: toml
+   :caption: technote.toml
+
+   [[technote.authors]]
+   name = {given = "Jonathan", family = "Sick"}
+   internal_id = "sickj"
+   orcid = "https://orcid.org/0000-0003-3001-676X"
+   [[technote.authors.affiliations]]
+   name = "Rubin Observatory Project Office"
+   internal_id = "RubinObs"
+   address = "950 N. Cherry Ave., Tucson, AZ 85719, USA"
+
+   [[technote.authors]]
+   name = {given = "Frossie", family = "Economou"}
+   internal_id = "economouf"
+   orcid = "https://orcid.org/0000-0002-8333-7615"
+   [[technote.authors.affiliations]]
+   name = "Rubin Observatory Project Office"
+   internal_id = "RubinObs"
+   address = "950 N. Cherry Ave., Tucson, AZ 85719, USA"
+
+To change the order of authors, you can move the ``[[technote.authors]]`` tables around in the file.
+Don't forget to keep the ``[[technote.authors.affiliations]]`` tables with their corresponding authors.
+
+Updating author metadata
+========================
+
+Occasionally the author metadata in `authordb.yaml`_ will change.
+To update the author metadata in your technote, run:
+
+.. prompt:: bash
+
+   make sync-authors
+
+Related documentation
+=====================
+
+- :external+technote:ref:`Schema for the [[technote.authors]] table in technote.toml in the Technote package documentation <toml-technote-authors>`
+- `Configuring authors <https://technote.lsst.io/user-guide/configure-authors.html>`__, from the Technote package documentation