diff --git a/CHANGELOG.md b/CHANGELOG.md index d4a99680..214eaca8 100644 --- 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. - + +## 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 deleted file mode 100644 index f9e4b50e..00000000 --- a/changelog.d/20230911_120423_jsick_DM_40684.md +++ /dev/null @@ -1,9 +0,0 @@ -### Backwards-incompatible changes - -- 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). -- Documenteer now requires Python 3.11 or later. -- Documenteer required Pydantic 2.0 or later. - -### Other changes - -- Adopted Scriv for maintaining the change log. diff --git a/changelog.d/20231012_194757_jsick_DM_41179.md b/changelog.d/20231012_194757_jsick_DM_41179.md deleted file mode 100644 index 95166829..00000000 --- a/changelog.d/20231012_194757_jsick_DM_41179.md +++ /dev/null @@ -1,17 +0,0 @@ - - -### Backwards-incompatible changes - -- - -### New features - -- - -### Bug fixes - -- `Retry` is now imported directly from `urllib3` instead of the vendored version in requests. - -### Other changes - -- Updated to technote 0.3.0a7. diff --git a/changelog.d/20231018_165310_jsick_DM_41214.md b/changelog.d/20231018_165310_jsick_DM_41214.md deleted file mode 100644 index 8d08ebc3..00000000 --- a/changelog.d/20231018_165310_jsick_DM_41214.md +++ /dev/null @@ -1,8 +0,0 @@ -### Backwards-incompatible changes - -- Now requires Sphinx 7 and later (and docutils 0.20 and later) - -### New features - -- 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. -- Rubin technotes are now configured to automatically cache all bibfiles from the https://github.com/lsst/lsst-texmf repository. The `sphinxcontrib-bibtex` extension is available to technotes as well. diff --git a/changelog.d/20231024_170151_jsick_DM_41296.md b/changelog.d/20231024_170151_jsick_DM_41296.md deleted file mode 100644 index 44ea1f7d..00000000 --- a/changelog.d/20231024_170151_jsick_DM_41296.md +++ /dev/null @@ -1,18 +0,0 @@ -### Backwards-incompatible changes - -- Delete the `refresh-lsst-bib` CLI command. Technotes now automatically vendor lsst-texmf's bib files and cache them using `documenteer.ext.githubbibcache`. -- Delete the `build-stack-docs` CLI command, which was 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 - -- Add `sphinx-jinja` to the Rubin guides configuration by default. -- Add `sphinx-rediraffe` to the Rubin guides configuration by default. diff --git a/changelog.d/20231026_192111_jsick_DM_41370.md b/changelog.d/20231026_192111_jsick_DM_41370.md deleted file mode 100644 index 1f7ef53f..00000000 --- a/changelog.d/20231026_192111_jsick_DM_41370.md +++ /dev/null @@ -1,3 +0,0 @@ -### New features - -- Update to technote 0.3.0 diff --git a/changelog.d/20231128_164718_jsick_DM_41781.md b/changelog.d/20231128_164718_jsick_DM_41781.md deleted file mode 100644 index 901e86aa..00000000 --- a/changelog.d/20231128_164718_jsick_DM_41781.md +++ /dev/null @@ -1,17 +0,0 @@ - - -### Backwards-incompatible changes - -- - -### New features - -- - -### Bug fixes - -- - -### Other changes - -- Update to technote 0.5. This version fixes support for markdown files and requires structured author names. diff --git a/changelog.d/20231129_140754_jsick_DM_41905.md b/changelog.d/20231129_140754_jsick_DM_41905.md deleted file mode 100644 index c8f0ec44..00000000 --- a/changelog.d/20231129_140754_jsick_DM_41905.md +++ /dev/null @@ -1,21 +0,0 @@ - - -### Backwards-incompatible changes - -- - -### New features - -- Add new default Sphinx extensions for technotes: - - - sphinx-prompt - - sphinxcontrib-mermaid - - sphinx-diagrams - -### Bug fixes - -- - -### Other changes - -- diff --git a/changelog.d/20231201_154001_jsick_DM_41917.md b/changelog.d/20231201_154001_jsick_DM_41917.md deleted file mode 100644 index 6dfff9dd..00000000 --- a/changelog.d/20231201_154001_jsick_DM_41917.md +++ /dev/null @@ -1,5 +0,0 @@ -### New features - -- Use the Source Sans 3 variable font in technotes. -- Small improvements to the technote UI, including: linking to the *LSST the Docs* editions dashboards, showing the Rubin imagotype on mobile views, and moving the author listing to the main text column. In mobile, headers are also smaller and more compact to conserve vertical space. -- Upgrade to technote 0.6. diff --git a/changelog.d/20231212_141904_jsick_DM_42023.md b/changelog.d/20231212_141904_jsick_DM_42023.md deleted file mode 100644 index d9a6c3b9..00000000 --- a/changelog.d/20231212_141904_jsick_DM_42023.md +++ /dev/null @@ -1,7 +0,0 @@ -### New features - -- New command-line interface for technote authors. - - - `documenteer technote migrate` automates to the process of migrating an old technote to the new format. - - `documenteer technote add-author` adds an author to a technote's `technote.toml` file using data from the `authordb.yaml` file in https://github.com/lsst/lsst-texmf. - - `documenteer technote sync-authors` refreshing author information in a `technote.toml` file with information from the `authordb.yaml` file. This requires that individual authors have `internal_id` fields to correlate with `authordb.yaml`. diff --git a/docs/_rst_epilog.rst b/docs/_rst_epilog.rst index a1f8fa1d..8a4fc619 100644 --- 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 `__ .. Internal links diff --git a/docs/technotes/author-metadata.rst b/docs/technotes/author-metadata.rst new file mode 100644 index 00000000..8e76f37c --- /dev/null +++ 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 ` +- `Configuring authors `__, from the Technote package documentation diff --git a/docs/technotes/configuration.rst b/docs/technotes/configuration.rst index 20b6fbcd..3f20a347 100644 --- a/docs/technotes/configuration.rst +++ b/docs/technotes/configuration.rst @@ -1,6 +1,6 @@ -################################## -Sphinx configuration for technotes -################################## +############################ +Configuring the Sphinx build +############################ Documenteer provides centralized configuration for technotes. To use these configurations, you must first install Documenteer with the "technote" extra, see :ref:`installation guide `. @@ -10,52 +10,46 @@ To use these configurations, you must first install Documenteer with the "techno Basic configuration =================== -To use Documenteer's configuration in a Sphinx technote project, create a :file:`conf.py` file: +To use Documenteer's configuration in a Sphinx technote project, the Sphinx :file:`conf.py` file must contain the following import: .. code-block:: python + :caption: conf.py from documenteer.conf.technote import * -This configuration uses content from the :file:`metadata.yaml` file, also in the technote project, to set information such as the title and authors. +This configuration uses content from the :file:`technote.toml` file, also in the technote repository, along with defaults in Documenteer to configure the technote build. -.. _technote-custom-conf: +Customizing the Sphinx build +============================ -Extending your technote's configuration -======================================= +Most technote projects don't need to customize the Sphinx build beyond the defaults provided by Documenteer. +If you do need to customize the build, there are two ways to do so: :file:`technote.toml` and :file:`conf.py`. -You can enhance and customize your technote's configuration by adding additional lines of Python, after the ``import`` statement in your :file:`conf.py` file. -These lines extend, and even replace statements in the configuration provided by Documenteer, which you can see in :ref:`technote-conf-source`, below. +With technote.toml +------------------ -The follow sections point out some common configuration tasks. -For more information about Sphinx configuration in general, see the `Sphinx documentation`_. +The recommended way to customize the build, where possible, is to through the :external+technote:ref:`[technote.sphinx] ` table in the :file:`technote.toml` file. +Some key configurations provided through :file:`technote.toml` include: -.. _Sphinx documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html +- Adding additional Sphinx extensions (see :doc:`extensions`) +- Adding projects for Intersphinx (:external+technote:ref:`[technote.sphinx.intersphinx] `) +- Setting the exemptions for the link check (:external+technote:ref:`[technote.sphinx.linkcheck] `) +- Setting the "nitpick" mode and exemptions for warning on build issues -Adding a package to Intersphinx -------------------------------- +.. seealso:: -One scenario is adding additional projects to the Intersphinx_ configuration. -For example, to add the Python standard library so that built-in Python APIs can be referenced: + `Configuring the Sphinx build `__, from the Technote package documentation. -.. code-block:: python - - from documenteer.conf.technote import * - - intersphinx_mapping["python"] = ("https://docs.python.org/3", None) - -To additionally add the LSST Science Pipelines: - -.. code-block:: python - - from documenteer.conf.technote import * +With conf.py +------------ - intersphinx_mapping["python"] = ("https://pipelines.lsst.io", None) +If :file:`technote.toml` does not provide the configuration you need, you can customize the Sphinx build by adding additional lines of Python to your :file:`conf.py` file. +Any lines added to the :file:`conf.py` file can override the configuration provided by Documenteer, or set new Sphinx configurations. +The existing configurations provided by Documenteer are shown in :ref:`technote-conf-source`, below. -Adding a Sphinx extension -------------------------- +.. seealso:: -You can add additional `Sphinx extensions`_ to your Sphinx build to make use of custom reStructuredText directives and roles. -See :ref:`technote-adding-extensions`. + :external+technote:ref:`direct-sphinx-conf`, from the Technote package documentation. .. _technote-conf-source: diff --git a/docs/technotes/edit-locally.rst b/docs/technotes/edit-locally.rst new file mode 100644 index 00000000..960b33fc --- /dev/null +++ b/docs/technotes/edit-locally.rst @@ -0,0 +1,101 @@ +#################################### +Edit a technote on your own computer +#################################### + +For most writers, the best way to edit a technote is on a computer you control and can install software on. +This might be your own laptop, or a computer account in the cloud like the Rubin Science Platform or GitHub Codespaces. + +If you don't already have a technote repository set up, :doc:`start-a-technote` first. + +Set up +====== + +Clone the repository +-------------------- + +First clone the GitHub repository containing your technote. +In a terminal, run :samp:`git clone https://github.com/{repo}`. + +The URL for the repository is provided by the Slack bot when you created the technote. + +Initialize the Python environment +--------------------------------- + +In a terminal, from the root of the repository, run: + +.. prompt:: bash + + make init + +This installs two Python packages: tox_ and pre-commit_. +Both of these tools create their own isolated Python environments to actually run the document builder and linter in. +Because of that, you don't need to rely on a specific Rubin Conda environment to build technotes. + +.. important:: + + Tox and pre-commit generally use the Python that they were installed with. + Documenteer requires Python 3.11 or later. + To check what version of Python you have, run: + + .. prompt:: bash + + python --version + +Build the technote's web page +----------------------------- + +In a terminal, from the root of the repository, run: + +.. prompt:: bash + + make html + +This will build the technote's web page and put it in the :file:`_build/html` directory. +On a Mac, you can open the page in your browser: + +.. prompt:: bash + + open _build/html/index.html + +Under the hood, :command:`make html` invokes tox_ and its `html` environment to build the technote in an isolated Python environment. + +Running linters +--------------- + +Technote projects are configured to use linters to check for common issues. + +To run the linters on-demand, run: + +.. prompt:: bash + + make lint + +That command runs both the Pre-commit_ hooks and the link checker. +If you ran :command:`make init`, the Pre-commit hooks will also run automatically before every Git commit. + +Resetting your environment +-------------------------- + +Both the Python environment and the web site build are cached. +You might want to reset those caches if the website is not building properly, or if you suspect that the Python environment is out of date (for example, a new version of Documenteer is available). +To delete the caches, run: + +.. prompt:: bash + + make clean + +Then run :command:`make html` again to rebuild the website in a fresh environment. + +.. tip:: + + You can be more selective about what you clean. + If you only want to delete the website cache, but keep all the installed Python packages in the Python environment, run: + + .. prompt:: bash + + rm -rf _build + +Related documentation +--------------------- + +- :doc:`edit-on-github` diff --git a/docs/technotes/edit-on-github.rst b/docs/technotes/edit-on-github.rst new file mode 100644 index 00000000..801562bf --- /dev/null +++ b/docs/technotes/edit-on-github.rst @@ -0,0 +1,33 @@ +######################################### +Editing a technote with the GitHub web UI +######################################### + +For small edits, you can edit a technote directly from GitHub's website. +The benefit of this approach is that you don't need to clone a repository or install any software to contribute to a Rubin technote. +You can even get a branch-based preview of your changes by creating a pull request. +The downside is that you only get feedback on the build status and linter after you've committed your changes. + +Using the edit-on-github feature +-------------------------------- + +You can edit a technote directly on GitHub's website. +You can make a single commit directly from GitHub's website. +To open this interface, either: + +- Navigate to the :file:`index.rst` or :file:`index.md` file on the technote's GitHub page and press the :kbd:`e` key (alternatively click the pencil icon in the top right corner of the file view). +- From the technote's pubilshed page, click the :guilabel:`Edit on GitHub` link on the left sidebar, under the :guilabel:`Source` heading. + +Make your edits and end a commit message. +It's recommended to commit to a new branch so that you can preview your changes in a pull request before merging them. + +For more details on this feature, see GitHub's `documentation on Editing files `__. + +Using github.dev +---------------- + +An alternative approach is to use the [github.dev](https://github.dev) service. +Open the technote's GitHub page in your browser and press the :kbd:`.` key. +This opens a basic VS Code editor in your browser. +You can edit multiple files and commit your changes directly from the browser. + +For more details on this feature, see GitHub's `documentation on github.dev `__. diff --git a/docs/technotes/how-your-technote-gets-published.rst b/docs/technotes/how-your-technote-gets-published.rst new file mode 100644 index 00000000..11b279b0 --- /dev/null +++ b/docs/technotes/how-your-technote-gets-published.rst @@ -0,0 +1,31 @@ +########################################### +How your technote gets published to the web +########################################### + +Technotes are published onto the web through the process of pushing commits to GitHub. +This page explains that process in more detail. + +The main website +================ + +Rubin technotes are published to the web on the ``lsst.io`` domain, with a dedicated subdomain that corresponds to the document's handle. +For example, if a document is assigned the handle ``DMTN-123``, it will be published to ``https://dmtn-123.lsst.io``. + +By default, this main page corresponds to the latest build from the technote repository's ``main`` branch. + +Views for other branches and tags +================================= + +If you push a commit to a branch other than ``main``, or if you push a tag, the technote will be published to a different URL. +You can find a listing of these alternative editions of the technote at the ``/v`` URL path (or click the :guilabel:`View all versions` link in the left sidebar of the technote webpage). + +How GitHub Actions builds and publishes the technote +==================================================== + +Technotes are built and published to the web by a GitHub Actions workflow. +By default, this workflow is the :file:`.github/workflows/ci.yaml` workflow. +You can view the status and logs for GitHub Actions workflows at the :guilabel:`Actions` tab of the technote repository. +For more information, see `GitHub's documentation on GitHub Actions `__. + +The default :file:`ci.yaml` workflow delegates to a reusable workflow in https://github.com/lsst-sqre/rubin-sphinx-technote-workflows. +By default, this workflow runs the ``make html`` command to build the technote. diff --git a/docs/technotes/index.rst b/docs/technotes/index.rst index 0ac233c0..bb9ef5ec 100644 --- a/docs/technotes/index.rst +++ b/docs/technotes/index.rst @@ -10,14 +10,25 @@ Documenteer provides centralized configuration and tooling for technotes. :caption: Getting started :titlesonly: + start-a-technote + edit-locally + edit-on-github + how-your-technote-gets-published migrate .. toctree:: :maxdepth: 2 - :caption: Configuration + :caption: Metadata :titlesonly: + author-metadata document-status + +.. toctree:: + :maxdepth: 2 + :caption: Sphinx configuration + :titlesonly: + configuration extensions diff --git a/docs/technotes/migrate.rst b/docs/technotes/migrate.rst index e0e074d9..7e9100c8 100644 --- a/docs/technotes/migrate.rst +++ b/docs/technotes/migrate.rst @@ -11,6 +11,8 @@ This page provides a guide to migrating your technical note to the new format. To get started on your migration, be sure to have your technote repository checked-out locally. Work on a ticket branch, `per the Developer Guide `__, so you can check your work with a pull request before merging to the ``main`` branch. +.. _technote-migration-tool: + Running the migration tool ========================== @@ -159,13 +161,16 @@ The new technote format requires some changes to this file: the title is now par .. tip:: Besides these changes, your technote can also be written in Markdown (:file:`index.md`). - If you wish to switch from ReStructuredText to markdown, install pandoc and run: + If you wish to switch from ReStructuredText to Markdown, you can use MyST Parser's migration tool: .. prompt:: bash - pandoc -f rst -t markdown -o index.md index.rst + 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 `). - Then, delete the original :file:`index.rst` file and edit :file:`index.md` to fix any formatting issues. + Finally, delete the original :file:`index.rst` file and edit :file:`index.md` to fix any formatting issues. .. prompt:: bash diff --git a/docs/technotes/start-a-technote.rst b/docs/technotes/start-a-technote.rst new file mode 100644 index 00000000..b4e107c0 --- /dev/null +++ b/docs/technotes/start-a-technote.rst @@ -0,0 +1,35 @@ +#################### +Start a new technote +#################### + +Rubin Observatory staff can start a new technote through their LSSTC Slack workspace account. +This page explains how to create a new technote project in either the Sphinx or ReStructuredText format. + +Prerequisites +============= + +To create and edit a technote, you'll need access to the `LSSTC Slack workspace`_. +You'll also need push access to the GitHub organization where your technote is hosted (different document series are hosted in different GitHub organizations, corresponding to the Rubin subsystem or team). +If you don't have push access in a whole organization, you can alternatively ask a leader in that organization to add you as a collaborator on the technote's repository once it's created. + +Create a technote repository through Slack +========================================== + +1. In Slack, open a |dmw-sqrbot| and type: + +.. code-block:: text + + 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` diff --git a/src/documenteer/storage/localtemplates/technote/Makefile b/src/documenteer/storage/localtemplates/technote/Makefile index b16ff8ea..d01cb272 100644 --- a/src/documenteer/storage/localtemplates/technote/Makefile +++ b/src/documenteer/storage/localtemplates/technote/Makefile @@ -9,7 +9,7 @@ html: .PHONY: lint: - tox run -e lint,link-check + tox run -e lint,linkcheck .PHONY: add-author: diff --git a/src/documenteer/storage/localtemplates/technote/README.rst b/src/documenteer/storage/localtemplates/technote/README.rst index d5199633..549a85dd 100644 --- a/src/documenteer/storage/localtemplates/technote/README.rst +++ b/src/documenteer/storage/localtemplates/technote/README.rst @@ -1,4 +1,4 @@ -.. image:: https://img.shields.io/badge/{{ cookiecutter.repo_name|replace("-", "--") }}-lsst.io-brightgreen.svg +.. image:: https://img.shields.io/badge/{{ cookiecutter.series|lower }}--{{ cookiecutter.serial_number }}-lsst.io-brightgreen.svg :target: {{ cookiecutter.url }} .. image:: https://github.com/{{ cookiecutter.github_namespace }}/workflows/CI/badge.svg :target: https://github.com/{{ cookiecutter.github_namespace }}/actions/ @@ -15,7 +15,7 @@ **Links:** - Publication URL: {{ cookiecutter.url }} -- Alternative editions: {{ cookiecutter.url }}/v +- Alternative editions: {{ cookiecutter.url }}v - GitHub repository: https://github.com/{{ cookiecutter.github_namespace }} - Build system: https://github.com/{{ cookiecutter.github_namespace }}/actions/ @@ -40,7 +40,7 @@ Publishing changes to the web ============================= This technote is published to {{ cookiecutter.url }} 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 {{ cookiecutter.url }}/v. +When you push changes to a another branch, a preview of the technote is published to {{ cookiecutter.url }}v. Editing this technical note =========================== diff --git a/src/documenteer/storage/localtemplates/technote/tox.ini b/src/documenteer/storage/localtemplates/technote/tox.ini index 2af08c00..210e9ef3 100644 --- a/src/documenteer/storage/localtemplates/technote/tox.ini +++ b/src/documenteer/storage/localtemplates/technote/tox.ini @@ -16,6 +16,7 @@ commands = sphinx-build --keep-going -n -W -T -b linkcheck -d _build/doctrees . _build/linkcheck [testenv:lint] +deps = pre-commit commands = pre-commit run --all-files