documenteer 2.1.0__tar.gz → 2.2.0__tar.gz

{documenteer-2.1.0 → documenteer-2.2.0}/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.2.0'></a>
+## 2.2.0 (2025-08-06)
+
+### New features
+
+- Updated the `documenteer technote migrate` command to use Documenteer 2.0 for new technotes.
+- Technote migration documentation now uses uv/uvx for running migration tools.
+- Improved the formatting for reference section in technotes with the Rubin BibTeX style:
+
+  - If an entry has more than 7 authors, the first three authors are listed, followed by "and others."
+  - LaTeX macros for journals are now converted to their expected names in the bibliography.
+
+### Other changes
+
+- Cleanup the API documentation for cleaner documentation builds.
+
+<a id='changelog-2.1.1'></a>
+## 2.1.1 (2025-07-17)
+
+### Bug fixes
+
+- When adding or updating authors in `technote.toml`, Documenteer avoids setting null values. TOML represents null values as absent keys, but previous versions of Documenteer included null `ror` values.
+
 <a id='changelog-2.1.0'></a>
 ## 2.1.0 (2025-07-16)
 

{documenteer-2.1.0 → documenteer-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.1.0
+Version: 2.2.0
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io

{documenteer-2.1.0 → documenteer-2.2.0}/docs/Makefile

@@ -1,7 +1,7 @@
 # Makefile for Sphinx documentation
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -n
+SPHINXOPTS    = -n -W
 SPHINXBUILD   = sphinx-build
 BUILDDIR      = _build
 

{documenteer-2.1.0 → documenteer-2.2.0}/docs/_rst_epilog.rst

@@ -62,6 +62,7 @@
 .. _`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
+.. _`uv`: https://docs.astral.sh/uv/
 
 .. |dmw-squarebot| replace:: `direct message with @squarebot <https://slack.com/app_redirect?app=A07PWG9UG9M&team=T02SVMGU4>`__
 

{documenteer-2.1.0 → documenteer-2.2.0}/docs/changelog.md

@@ -2,6 +2,29 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.2.0'></a>
+## 2.2.0 (2025-08-06)
+
+### New features
+
+- Updated the `documenteer technote migrate` command to use Documenteer 2.0 for new technotes.
+- Technote migration documentation now uses uv/uvx for running migration tools.
+- Improved the formatting for reference section in technotes with the Rubin BibTeX style:
+
+  - If an entry has more than 7 authors, the first three authors are listed, followed by "and others."
+  - LaTeX macros for journals are now converted to their expected names in the bibliography.
+
+### Other changes
+
+- Cleanup the API documentation for cleaner documentation builds.
+
+<a id='changelog-2.1.1'></a>
+## 2.1.1 (2025-07-17)
+
+### Bug fixes
+
+- When adding or updating authors in `technote.toml`, Documenteer avoids setting null values. TOML represents null values as absent keys, but previous versions of Documenteer included null `ror` values.
+
 <a id='changelog-2.1.0'></a>
 ## 2.1.0 (2025-07-16)
 

{documenteer-2.1.0 → documenteer-2.2.0}/docs/dev/api/documenteer.ext.rst

@@ -2,12 +2,12 @@
 documenteer.ext
 ###############
 
-.. automodapi:: documenteer.ext.openapi
-
 .. automodapi:: documenteer.ext.bibtex
    :no-inherited-members:
    :no-inheritance-diagram:
 
+.. automodapi:: documenteer.ext.githubbibcache
+
 .. automodapi:: documenteer.ext.jira
    :no-inheritance-diagram:
 
@@ -16,3 +16,9 @@ documenteer.ext
 
 .. automodapi:: documenteer.ext.mockcoderefs
    :no-inheritance-diagram:
+
+.. automodapi:: documenteer.ext.openapi
+
+.. automodapi:: documenteer.ext.remotecodeblock
+
+.. automodapi:: documenteer.ext.robots

{documenteer-2.1.0 → documenteer-2.2.0}/docs/documenteer.toml

@@ -44,7 +44,8 @@ technote = "https://technote.lsst.io/"
 
 [sphinx.linkcheck]
 ignore = [
-    "https://mermaid-js.github.io"
+    "https://mermaid-js.github.io",
+    "https://rubin-obs.slack.com"
 ]
 
 [sphinx.redirects]

{documenteer-2.1.0 → documenteer-2.2.0}/docs/technotes/migrate.rst

@@ -5,7 +5,7 @@ Migrate legacy reStructuredText/Sphinx technical notes
 ######################################################
 
 Introduced in December 2023, Rubin Observatory has a new technical note format for Markdown and reStructuredText documents.
-This update provides many `new features <https://community.lsst.org/t/the-next-generation-of-rubin-observatory-technotes-with-documenteer-1-0/8166>`__ included a responsive and branded page design, Markdown support, improved build configuration, automated bibliography management, and citation-ready metadata.
+This update provides many `new features <https://community.lsst.org/t/the-next-generation-of-rubin-observatory-technotes-with-documenteer-1-0/8166>`__ including a responsive and branded page design, Markdown support, improved build configuration, automated bibliography management, and citation-ready metadata.
 
 This page shows how to migrate your existing technotes with a command-line tool that largely automates the process.
 This page also provides file-by-file notes in case you need to revise the migration.
@@ -16,39 +16,17 @@ This page also provides file-by-file notes in case you need to revise the migrat
 
    LaTeX-format technotes are unaffected by this migration.
 
-Step 1. Install pipx
-====================
+Use the migration tool
+======================
 
-The migration tool needs **Python 3.11 or later**.
-You can verify this by running ``python --version`` from your shell.
+Documenteer provides a command-line tool, :command:`documenteer technote migrate`, to migrate legacy technotes to the new format.
+The migration tool requires:
 
-This official migration procedure uses the pipx_ tool to install and run the migration tool in an isolated Python environment.
-You can verify that pipx_ is installed by running ``pipx --version`` from your shell and checking for a version number.
+- Python 3.12 or later
+- The :command:`uvx` command from the `uv`_ package
 
-If you don't have the :command:`pipx` command-line tool already, you can install ``pipx`` several ways:
-
-.. tab-set::
-
-   .. tab-item:: pip
-
-      .. prompt:: bash
-
-         python -m pip install pipx
-
-   .. tab-item:: conda-forge
-
-      .. prompt:: bash
-
-         conda install -c conda-forge pipx
-
-   .. tab-item:: homebrew
-
-      .. prompt:: bash
-
-         brew install pipx
-
-Step 2. Clone your technote and create a branch
-===============================================
+Step 1. Clone your technote and create a branch
+-----------------------------------------------
 
 Since the migration is performed locally, you need to clone the repository:
 
@@ -60,12 +38,12 @@ Then create a branch for the migration (see the `Developer Guide <https://develo
 
 .. code-block:: bash
 
-   git switch -c {...}
+   git switch -c technote-migration
 
 Working from a branch allows you to create a pull request to verify the migration before merging it into the main branch.
 
-Step 3. Look up author IDs
-==========================
+Step 2. Look up author IDs
+--------------------------
 
 The migration tool needs the IDs of the technote's authors to fully configure the technote's metadata.
 
@@ -74,15 +52,39 @@ For example, ``sickj`` is the ID for Jonathan Sick.
 
 .. _technote-migration-tool:
 
-Step 4. Run the migration tool
-==============================
+Step 3. Run the migration tool
+------------------------------
 
 From the root of the cloned technote repository, run the migration tool, listing any identified authors that are relevant to your technote:
 
 .. code-block:: bash
    :caption: Set author IDs with the -a option
 
-   pipx run documenteer technote migrate -a sickj -a economouf
+   uvx documenteer technote migrate -a sickj -a economouf
+
+.. dropdown:: Details for installing uv/uvx...
+
+   The migration tool needs **Python 3.12 or later**.
+   You can verify this by running ``python --version`` from your shell.
+
+   This official migration procedure uses the :command:`uvx` command from uv_ to install and run the migration tool in an isolated Python environment.
+
+   If you don't have the :command:`uvx` command-line tool already, you can install ``uv`` several ways:
+
+   .. tab-set::
+
+      .. tab-item:: pip
+
+         .. prompt:: bash
+
+            python -m pip install uv
+
+      .. tab-item:: homebrew
+
+         .. prompt:: bash
+
+            brew install uv
+
 
 When the migration runs, it shows a summary of the files changed and deleted.
 Use ``git diff`` to review the changes in case you need to make tweaks before committing.
@@ -91,22 +93,21 @@ If you want to learn more about the changes made by the migration tool, you can
 
 .. _technote-migration-markdown:
 
-Step 5 (optional). Migrate to Markdown
-======================================
+Step 4 (optional). Migrate to Markdown
+--------------------------------------
 
 The new technote format supports Markdown as well as reStructuredText.
 If you wish to use Markdown, you can use MyST Parser's migration tool:
 
 .. prompt:: bash
 
-   pipx install "rst-to-myst[sphinx]"
-   rst2myst convert index.rst
+   uvx --from "rst-to-myst[sphinx]" rst2myst convert index.rst
 
 The Markdown flavor used by the new technote format is MyST Markdown, which is a superset of CommonMark Markdown with support for Sphinx roles and directives.
 See the `MyST Parser documentation <https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-directives>`__ for more information.
 
-Step 6 (optional). Build the technote locally
-=============================================
+Step 5 (optional). Build the technote locally
+---------------------------------------------
 
 You can build the technote locally to verify that the migrated technote compiles successfully.
 
@@ -136,8 +137,8 @@ You might also want to run the linter to check links and find common issues:
 If you have any questions or issues about the build, you should still proceed with committing and creating a pull request (see next step).
 This way you can link to the repository when you reach out for help in `#square-docs-support`_ on Slack.
 
-Step 7. Commit the migration, pull request, and merge
-=====================================================
+Step 6. Commit the migration, pull request, and merge
+-----------------------------------------------------
 
 At this point, you should have a working technote in the new format.
 If you haven't already, commit your work, push your branch to the GitHub repository, and open a pull request.
@@ -225,26 +226,6 @@ The new technote format requires some changes to this file: the title is now par
 Additionally, the new technote format supports Markdown as well as reStructuredText.
 See :ref:`migrate to Markdown <technote-migration-markdown>` to learn how to switch to Markdown.
 
-.. tip::
-
-   Besides these changes, your technote can also be written in Markdown (:file:`index.md`).
-   If you wish to switch from ReStructuredText to Markdown, you can use MyST Parser's migration tool:
-
-   .. prompt:: bash
-
-      pipx install "rst-to-myst[sphinx]"
-      rst2myst convert index.rst
-
-   This procedure uses pipx_ to install the ``rst-to-myst`` tool in an isolated Python environment (you might have already installed pipx_ to run the :ref:`main migration tool <technote-migration-tool>`).
-
-   Finally, delete the original :file:`index.rst` file and edit :file:`index.md` to fix any formatting issues.
-
-   .. prompt:: bash
-
-      git rm index.rst
-      git add index.md
-      git commit -m "Switch to Markdown format"
-
 Title
 ~~~~~
 
@@ -402,7 +383,7 @@ To start, add a :file:`.pre-commit-config.yaml` file:
 
 .. tip::
 
-   You can add additional pre-commit hooks to this file to suite your needs.
+   You can add additional pre-commit hooks to this file to suit your needs.
    See Pre-commit's `directory of available hooks <https://pre-commit.com/hooks.html>`__ for ideas.
 
 requirements.txt file (updated)

documenteer-2.2.0/docs/technotes/start-a-technote.rst

@@ -0,0 +1,45 @@
+####################
+Start a new technote
+####################
+
+Rubin Observatory staff can start a new technote through the rubin-obs.slack.com workspace.
+This page explains how to create a new technote project in either the Markdown or reStructuredText format.
+
+Prerequisites
+=============
+
+To create and edit a technote, you'll need access to the rubin-obs.slack.com workspace.
+You'll also need push access to the technote.
+If you don't have push access in the whole organization, you can ask an organization administrator to add you as a `collaborator <https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization>`__ to the technote's repository after you create it.
+
+ To create and edit a technote, you'll need:
+
+  1. Access to the rubin-obs.slack.com workspace
+  2. Push access to edit the technote repository after it's created
+
+For GitHub access, you have two options:
+
+- **Organization member**: If you have push access to the relevant GitHub organization (different technote series are hosted in different organizations), you'll automatically have access to your new technote repository.
+- **External collaborator**: If you don't have organization-wide access, ask an organization administrator to add you as a `collaborator <https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization>`__ to the technote repository once it's created.
+
+Create a technote repository through Slack
+==========================================
+
+1. In the rubin-obs.slack.com workspace, send a message to ``@Squarebot``:
+
+.. code-block:: text
+
+   /msg @Squarebot create project
+
+2. In response, a message with a drop-down appears. From the drop-down, select a template based on the preferred format:
+
+   - For reStructuredText: :menuselection:`Documents --> Technote (reStructuredText)`
+   - For Markdown: :menuselection:`Documents --> Technote (Markdown)`
+
+3. Watch for threaded replies in Slack that provide a link to the GitHub repository and the technote's publication URL.
+
+Next steps
+==========
+
+- :doc:`edit-locally`
+- :doc:`edit-on-github`

documenteer-2.2.0/src/documenteer/ext/bibtex.py

@@ -0,0 +1,147 @@
+"""Support for Rubin BibTeX files for pybtex/sphinxcontrib.bibtex."""
+
+import typing
+
+import pybtex.style.formatting.plain
+from pybtex.database import Entry, Person
+from pybtex.plugin import register_plugin
+from pybtex.style.formatting import toplevel
+from pybtex.style.template import (
+    FieldIsMissing,
+    Node,
+    field,
+    first_of,
+    href,
+    join,
+    node,
+    optional,
+    optional_field,
+    sentence,
+    tag,
+)
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
+from ..version import __version__
+
+__all__ = ["setup"]
+
+
+@node
+def truncated_names(
+    children: list[Node], context: typing.Any, role: str, **kwargs: typing.Any
+) -> Node:
+    """Return formatted names, truncating long author lists."""
+    assert not children  # noqa: S101 (matches pybtex original)
+
+    try:
+        persons = context["entry"].persons[role]
+    except KeyError:
+        raise FieldIsMissing(role, context["entry"]) from None
+
+    # If there are more than 7 authors we return the first 3.
+    if len(persons) > 7:
+        persons = persons[:3] + [Person("others")]
+    style = context["style"]
+    formatted_names = [
+        style.format_name(person, style.abbreviate_names) for person in persons
+    ]
+    return join(**kwargs)[formatted_names].format_data(context)
+
+
+class LsstBibtexStyle(pybtex.style.formatting.plain.Style):
+    """Bibtex style used for Rubin tech notes.
+
+    * Limits the number of authors for large author lists.
+    * Handles LaTeX journal macros.
+    """
+
+    # Allows a mapping of journal or series name found in the bibtex file
+    # to a more usable name for the Sphinx output. In particular ADS returns
+    # bib entries that assume latex commands exist to convert from \apj
+    # to ApJ or Astrophys. J as needed (allowing each style to decide how
+    # to report journal names).
+    bib_to_display_name: typing.ClassVar = {
+        r"\actaa": "Acta Astron.",
+        r"\aap": "A&A",
+        r"\aaps": "A&AS",
+        r"\aj": "AJ",
+        r"\ao": "Appl. Opt.",
+        r"\apj": "ApJ",
+        r"\apjl": "ApJL",
+        r"\apjs": "ApJS",
+        r"\apss": "Ap&SS",
+        r"\araa": "ARA&A",
+        r"\icarus": "Icarus",
+        r"\memsai": "Mem. Soc. Ast. Italiana",
+        r"\mnras": "MNRAS",
+        r"\nat": "Nature",
+        r"\pasa": "PASA",
+        r"\pasj": "PASJ",
+        r"\pasp": "PASP",
+        r"\physrep": "Phys. Rep.",
+        r"\prd": "Phys. Rev. D.",
+        r"\procspie": "Proc. SPIE",
+        "Society of Photo-Optical Instrumentation Engineers (SPIE) Conference"
+        " Series": "Proc. SPIE",
+    }
+
+    def _rewrite_field(self, e: Entry, field: str) -> None:
+        """Rewrite the field contents based on the bib name map."""
+        if field in e.fields:
+            bib_name = e.fields[field]
+            if modified_name := self.bib_to_display_name.get(bib_name):
+                e.fields[field] = modified_name
+
+    def get_article_template(self, e: Entry) -> Node:
+        # Fix up the journal name before rendering.
+        # In particular journal entries from ADS tend to use \apj style
+        # latex commands which need expanding.
+        self._rewrite_field(e, "journal")
+        return super().get_article_template(e)
+
+    def get_inproceedings_template(self, e: Entry) -> Node:
+        # Potentially modify the series string before formatting it.
+        self._rewrite_field(e, "series")
+        self._rewrite_field(e, "booktitle")
+        return super().get_inproceedings_template(e)
+
+    def format_docushare(self, e: Entry) -> str:
+        default_url = join["https://ls.st/", field("handle", raw=True)]
+
+        template = toplevel[
+            sentence[tag("b")["[", href[default_url, field("handle")], "]"]],
+            self.format_names("author"),
+            self.format_title(e, "title"),
+            sentence[field("year")],
+            sentence[optional_field("note")],
+            # Use URL if we have it, else provide own
+            first_of[
+                optional[self.format_url(e)],
+                # define our own URL
+                sentence["URL", href[default_url, default_url]],
+            ],
+        ]
+        return template.format_data(e)
+
+    def format_names(self, role: str, as_sentence: bool = True) -> Node:  # noqa: FBT001, FBT002
+        # Copied from pybtex but using a different names function that
+        # caps the number of authors.
+        formatted_names = truncated_names(
+            role, sep=", ", sep2=" and ", last_sep=", and "
+        )
+        if as_sentence:
+            return sentence[formatted_names]
+        else:
+            return formatted_names
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Add this plugin to the Sphinx application."""
+    register_plugin("pybtex.style.formatting", "lsst_aa", LsstBibtexStyle)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/ext/jira.py

@@ -14,7 +14,9 @@ from sphinx.util.typing import ExtensionMetadata
 
 from ..version import __version__
 
-log = getLogger(__name__)
+__all__ = ["setup"]
+
+logger = getLogger(__name__)
 
 
 def _make_ticket_node(

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/ext/lsstdocushare.py

@@ -14,6 +14,8 @@ if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
 
+__all__ = ["setup"]
+
 
 def lsstio_doc_shortlink_role(
     name: str,

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/ext/mockcoderefs.py

@@ -16,7 +16,9 @@ from sphinx.util.typing import ExtensionMetadata
 
 from ..version import __version__
 
-log = getLogger(__name__)
+__all__ = ["setup"]
+
+logger = getLogger(__name__)
 
 
 def mock_code_ref_role(

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/ext/openapi.py

@@ -15,7 +15,7 @@ from sphinx.util.typing import ExtensionMetadata
 
 from ..version import __version__
 
-__all__ = ["generate_openapi_spec", "setup"]
+__all__ = ["setup"]
 
 
 def generate_openapi_spec(app: Sphinx, config: Config) -> None:

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/ext/remotecodeblock.py

@@ -20,6 +20,8 @@ from sphinx.util.typing import ExtensionMetadata
 from .._requestsutils import requests_retry_session
 from ..version import __version__
 
+__all__ = ["setup"]
+
 logger = logging.getLogger(__name__)
 
 

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/ext/robots.py

@@ -99,7 +99,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
 
     Returns
     -------
-    ExtensionMetadata
+    sphinx.util.typing.ExtensionMetadata
         Extension metadata for Sphinx.
     """
     # Connect to the build-finished event

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/storage/localtemplates/technote/pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v5.0.0
     hooks:
       # - id: trailing-whitespace
       - id: check-yaml

documenteer-2.2.0/src/documenteer/storage/localtemplates/technote/requirements.txt

@@ -0,0 +1 @@
+documenteer[technote]>=2.0,<3

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer/storage/technotetoml.py

@@ -105,17 +105,26 @@ class TechnoteTomlFile:
     ) -> None:
         """Update a toml author table with the Author data."""
         name_table = tomlkit.inline_table()
-        name_table["given"] = author.given_name
-        name_table["family"] = author.family_name
+        if author.given_name is not None:
+            name_table["given"] = author.given_name
+        if author.family_name is not None:
+            name_table["family"] = author.family_name
+
         table["name"] = name_table
+
         table["internal_id"] = author.internal_id
+
         if author.orcid is not None:
             table["orcid"] = str(author.orcid)
 
         if "affiliations" not in table:
             table.add("affiliations", tomlkit.aot())
         affiliations_aot = cast(tomlkit.items.AoT, table["affiliations"])
-        existing_affiliation_ids = [a["internal_id"] for a in affiliations_aot]
+
+        existing_affiliation_ids = [
+            a["internal_id"] for a in affiliations_aot if "internal_id" in a
+        ]
+
         for affiliation in author.affiliations:
             if affiliation.internal_id not in existing_affiliation_ids:
                 # Add a new affiliation
@@ -134,4 +143,5 @@ class TechnoteTomlFile:
     ) -> None:
         t["name"] = affiliation_info.name
         t["internal_id"] = affiliation_info.internal_id
-        t["ror"] = str(affiliation_info.ror)
+        if affiliation_info.ror is not None:
+            t["ror"] = str(affiliation_info.ror)

{documenteer-2.1.0 → documenteer-2.2.0}/src/documenteer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.1.0
+Version: 2.2.0
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io