From a9cec4436dfecb08ab9c23b332d7a44d2d4f753f Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 28 Aug 2025 10:22:42 -0400 Subject: [PATCH 1/2] Update documentation for technote creation - Move specific documentation for working with Sphinx technotes from the developer guide to the new home in the Documenteer docs - Mention all types of templates - Update the instructions for creating a technote to use the /msg slash command - Other small updates --- project-docs/technotes.rst | 86 ++++++++++++-------------------------- 1 file changed, 26 insertions(+), 60 deletions(-) diff --git a/project-docs/technotes.rst b/project-docs/technotes.rst index 3453cc86..f711a86f 100644 --- a/project-docs/technotes.rst +++ b/project-docs/technotes.rst @@ -68,9 +68,10 @@ Technote series .. _which-series: -Operations vs Construction -========================== -The DMTN and SQR series will still exist in operations and so it may still be used. +Operations vs construction +-------------------------- + +The DMTN and SQR series still exist in operations and so it may still be used. In general if a topic fits in a given series use the series without hesitation. .. _technote-create: @@ -79,77 +80,42 @@ Create a technote ================= Creating a new technote is easy and takes just a moment. -In Slack, open a |dmw-squarebot| and type: +In the rubin-obs Slack, send a message to Squarebot: .. code-block:: text - create project + /msg @Squarebot create project + +From the drop-down, select **Documents > Technote ** for the format you wish to work in: + +- ``Documents > Technote (reStructuredText)`` creates web-native technotes using the same reStructuredText markup as Python docstrings and most Sphinx documentation +- ``Documents > Technote (Markdown)`` use the same HTML output as above, but with Markdown syntax +- ``Documents > Technote (lsstdoc LaTeX)`` is the LaTeX format for Rubin documents (PDF output) +- ``Documents > Technote (AASTeX LaTeX)`` for AAS preprints (PDF output) +- ``Documents > Technote (ADASS LaTeX)`` for ADASS conference proceedings (PDF output) +- ``Documents > Technote (ASCOM LaTeX)`` for Astronomy & Computing preprints (PDF output) +- ``Documents > Technote (SPIE LaTeX)`` for SPIE conference proceedings (PDF output) -From the drop-down, select **Documents > Technote (reStructuredText)** or **(lsstdoc LaTeX)** depending on the format you wish to work in. Once you select the template type and fill in the form on Slack, the bot will create and configure the technote on GitHub. Watch for Slack messages from the bot about the technote's GitHub repository and publication URL. +Updating a technote +------------------- + Any time you push to GitHub, your technote will be republished at its ``lsst.io`` site. Pushes to the ``main`` branch update your technote's main page, while updates to other branches update preview editions behind the ``/v/`` URL path. Click on the **Switch editions** or **Change version** link from your published technote to get links for other editions. -.. _technote-latex: - -Working with LaTeX-formatted technotes -====================================== - -LaTeX-formatted technotes use the ``lsstdoc`` class. -The `lsst-texmf documentation `__ explains how to write ``lsstdoc``-based documents. - .. _technote-rst: -Working with reStructuredText-formatted technotes -================================================= - -See the :doc:`/restructuredtext/style` for a primer on writing reStructuredText. -The sections below deal with specific issues for technote projects. - -.. _technote-rst-bib: - -Using bibliographies in reStructuredText technotes --------------------------------------------------- - -The lsst-texmf project includes `shared BibTeX bibliographic databases `_. -You can also use these bibliographies from reStructuredText technotes. +Working with reStructuredText or Markdown technotes +--------------------------------------------------- -First, add or uncomment the ``bibliography`` directive at the bottom of your technote's :file:`index.rst` file: +See the `Documenteer technote documentation `__ for information on writing and building reStructuredText or Markdown technotes. -.. code-block:: rst - - .. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib - :style: lsst_aa - -.. note:: - - Only include the :file:`local.bib` file if your technote's repository has one. - Use :file:`local.bib` to temporarily store bib items before you permanently `transfer them to the lsst-texmf project `_. - -The bibliographies in the :file:`lsstbib` directory are copies from the https://github.com/lsst/lsst-texmf repository. -Refresh the copies maintained in your technote's repository by running this command: - -.. code-block:: bash - - make refresh-bib - -To make citations in the technote's text, use the ``cite`` role. -For example: - -.. code-block:: rst - - :cite:`2007PASP..119.1462B` - -In-text citations are numbered, not author-year style. - -.. _technote-rst-metadata: +.. _technote-latex: -Editing metadata in reStructuredText technotes ----------------------------------------------- +Working with LaTeX-formatted technotes +-------------------------------------- -ReStructuredText-format technotes use a :file:`metadata.yaml` in their repositories to describe attributes like the document's title, author list, and abstract. -To change the technote's title or author list, for example, commit a change to the :file:`metadata.yaml` file. -See the comments in :file:`metadata.yaml` for a description of these fields. +The `lsst-texmf documentation `__ explains how to write ``lsstdoc``-based documents. From b6616ca3ce67fb50ec194d8fe299694eefec30b7 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 28 Aug 2025 10:41:55 -0400 Subject: [PATCH 2/2] Add note on author IDs --- project-docs/technotes.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/project-docs/technotes.rst b/project-docs/technotes.rst index f711a86f..a3c8aa7f 100644 --- a/project-docs/technotes.rst +++ b/project-docs/technotes.rst @@ -99,6 +99,12 @@ From the drop-down, select **Documents > Technote ** for the format you Once you select the template type and fill in the form on Slack, the bot will create and configure the technote on GitHub. Watch for Slack messages from the bot about the technote's GitHub repository and publication URL. +.. tip:: + + The template form asks for your *author ID*. + You can find your author ID in the `Author DB Google Sheet `__. + Send a pull request to update your entry in `authordb.yaml `__, or use the Google form linked from the ``#all-users`` channel in Slack. + Updating a technote -------------------