DM-41327: Document migration of technotes to new format

.github/SUPPORT.md

@@ -1,5 +1,5 @@
 Here are some ways to get help with Documenteer:
 
 - [Documentation](https://documenteer.lsst.io)
-- [Ask a question in #dm-docs (for LSST staff)](https://lsstc.slack.com/archives/C2B6DQBAL)
+- [Ask a question in #dm-docs-support (for Rubin staff)](https://lsstc.slack.com/archives/C2B6DQBAL)
 - [Post a GitHub issue](https://github.com/lsst-sqre/documenteer/issues/new)

docs/_rst_epilog.rst

@@ -13,7 +13,7 @@
 .. _sphinxcontrib-mermaid: https://github.com/mgaitan/sphinxcontrib-mermaid
 .. _Diagrams: https://diagrams.mingrammer.com/
 .. _sphinx-diagrams: https://github.com/j-martin/sphinx-diagrams
-.. _`#dm-docs`: https://lsstc.slack.com/archives/C2B6DQBAL
+.. _`#dm-docs-support`: https://lsstc.slack.com/archives/C2B6DQBAL
 .. _`DMTN-030`:
 .. _`DMTN-030 Science Pipelines Documentation Design`: https://dmtn-030.lsst.io
 .. _`Google Developer Style Guide`: https://developers.google.com/style/

docs/documenteer.toml

@@ -24,6 +24,9 @@ nitpick_ignore_regex = [
   ['py:.*', 'pydantic.*'],
 ]
 python_api_dir = "dev/api/contents"
+exclude = [
+  "technotes/_templates/*"
+]
 
 [sphinx.theme]
 header_links_before_dropdown = 5

docs/guides/pipelines/cpp-api-linking.rst

@@ -23,7 +23,7 @@ The Sphinx configuration for the pipelines.lsst.io project includes a special :r
 
    Use the :ref:`stack-docs listcc command <lsstcc-listcc>` to identify linkable API signatures.
    As a last resort, you may want to manually create a relative hyperlink.
-   Contact `#dm-docs`_ on Slack for help.
+   Contact `#dm-docs-support`_ on Slack for help.
 
 .. role:: lsstcc
 

docs/technotes/_templates/README.md

@@ -0,0 +1,42 @@
+[![Website](https://img.shields.io/badge/example--000-lsst.io-brightgreen.svg)](https://example-000.lsst.io)
+[![CI](https://github.com/lsst/example-000/actions/workflows/ci.yaml/badge.svg)](https://github.com/lsst/example-000/actions/workflows/ci.yaml)
+
+# Document Title
+
+## EXAMPLE-000
+
+A short description of this document.
+
+### Links
+
+- Publication URL: https://example-000.lsst.io
+- Alternative editions: https://example-000.lsst.io/v
+- GitHub repository: https://github.com/lsst/example-000
+- Build system: https://github.com/lsst/example-000/actions/
+
+## Build this technical note
+
+You can clone this repository and build the technote locally if your system has Python 3.11 or later:
+
+```bash
+git clone https://github.com/lsst/example-000
+cd example-000
+make init
+make html
+```
+
+Repeat the `make html` command to rebuild the technote after making changes.
+If you need to delete any intermediate files for a clean build, run `make clean`.
+
+The built technote is located at `_build/html/index.html`.
+
+## Publishing changes to the web
+
+This technote is published to https://example-000.lsst.io whenever you push changes to the `main` branch on GitHub.
+When you push changes to a another branch, a preview of the technote is published to https://example-000.lsst.io/v.
+
+## Editing this technical note
+
+The main content of this technote is in `index.md` (a Markdown file).
+Metadata and configuration is in the `technote.toml` file.
+For guidance on creating content and information about specifying metadata and configuration, see the Documenteer documentation: https://documenteer.lsst.io/technotes.

docs/technotes/_templates/README.rst

@@ -0,0 +1,50 @@
+.. image:: https://img.shields.io/badge/example--000-lsst.io-brightgreen.svg
+   :target: https://example-000.lsst.io
+.. image:: https://github.com/lsst/example-000/workflows/CI/badge.svg
+   :target: https://github.com/lsst/example-000/actions/
+
+##############
+Document Title
+##############
+
+EXAMPLE-000
+===========
+
+A short description of this document.
+
+**Links:**
+
+- Publication URL: https://example-000.lsst.io
+- Alternative editions: https://example-000.lsst.io/v
+- GitHub repository: https://github.com/lsst/example-000
+- Build system: https://github.com/lsst/example-000/actions/
+
+Build this technical note
+=========================
+
+You can clone this repository and build the technote locally if your system has Python 3.11 or later:
+
+.. code-block:: bash
+
+   git clone https://github.com/lsst/example-000
+   cd example-000
+   make init
+   make html
+
+Repeat the ``make html`` command to rebuild the technote after making changes.
+If you need to delete any intermediate files for a clean build, run ``make clean``.
+
+The built technote is located at ``_build/html/index.html``.
+
+Publishing changes to the web
+=============================
+
+This technote is published to https://example-000.lsst.io whenever you push changes to the ``main`` branch on GitHub.
+When you push changes to a another branch, a preview of the technote is published to https://example-000.lsst.io/v.
+
+Editing this technical note
+===========================
+
+The main content of this technote is in ``index.rst`` (a reStructuredText file).
+Metadata and configuration is in the ``technote.toml`` file.
+For guidance on creating content and information about specifying metadata and configuration, see the Documenteer documentation: https://documenteer.lsst.io/technotes.

docs/technotes/document-status.rst

@@ -0,0 +1,61 @@
+#############################################################
+Describing the document status (draft, deprecated, or stable)
+#############################################################
+
+Technotes are continuously updated on the web as you add commits and merge pull requests.
+Your "drafts" are visible to the rest of the observatory, and even the public, to speed up collaboration and provide transparency.
+You can communicate the status of the document by setting metadata in :file:`technote.toml`.
+For example, you can specify that the technote is an incomplete draft, or that the technote is deprecated and is now replaced by another set of documents.
+
+Setting "draft" status
+======================
+
+If the technote is incomplete and being actively written, you can set the status to "draft:"
+
+.. code-block:: toml
+   :caption: technote.toml
+
+   [technote.state]
+   status = "draft"
+
+Setting "stable" status
+=======================
+
+If the technote is complete, accurate and no longer being actively worked upon, you can set the status to "stable:"
+
+.. code-block:: toml
+   :caption: technote.toml
+
+   [technote.state]
+   status = "stable"
+
+This is the default state if one is not specified in :file:`technote.toml`.
+
+Setting "deprecated" status
+===========================
+
+If your technote is no longer accurate or relevant, you can mark it as deprecated:
+
+.. code-block:: toml
+   :caption: technote.toml
+
+   [technote.state]
+   status = "deprecated"
+   note = "This technote is deprecated because [...]"
+
+If the technote has been replaced by one or more other documents, you can link to them with a ``supersceding_urls`` array:
+
+.. code-block:: toml
+   :caption: technote.toml
+
+   [technote.state]
+   status = "deprecated"
+   note = "This technote is deprecated because [...]"
+
+   [[technote.state.supersceding_urls]]
+   title = "New technote"
+   url = "https://example.lsst.io/"
+
+   [[technote.state.supersceding_urls]]
+   title = "Another document"
+   url = "https://example-two.lsst.io/"

docs/technotes/index.rst

@@ -2,18 +2,27 @@
 Technotes
 #########
 
-Rubin technical notes (or *technotes*) are often written in reStructuredText, especially within LSST Data Management.
+Rubin technical notes (or *technotes*) are often written in reStructuredText or Markdown.
 Documenteer provides centralized configuration and tooling for technotes.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting started
+   :titlesonly:
+
+   migrate
+
 .. toctree::
    :maxdepth: 2
    :caption: Configuration
+   :titlesonly:
 
+   document-status
    configuration
 
 .. seealso::
 
    To learn more about technotes:
 
-   - LSST DM Developer Guide: `Technotes for stand-alone technical documentation <https://developer.lsst.io/project-docs/technotes.html>`_
+   - Rubin Observatory DM Developer Guide: `Technotes for stand-alone technical documentation <https://developer.lsst.io/project-docs/technotes.html>`_
    - `SQR-000: The LSST DM Technical Note Publishing Platform <https://sqr-000.lsst.io>`_