Add more drafts

docs/index.rst

@@ -23,6 +23,7 @@ building the docs and releases and publishing it on PyPI.
   :hidden:
 
   topics/testing/index
+  topics/documenting/index
   topics/building
   topics/publishing
   topics/organization

docs/topics/building.md

@@ -21,6 +21,7 @@ Building your Salt extension's wheel is easy:
 python -m build --outdir dist/
 ```
 
-Then you can find the installable wheel (`.whl` file extension) inside the `dist` directory. In theory, this file can be installed via `pip`, provided you don't rename it.
+Then you can find the installable wheel (`.whl` file extension) inside the `dist` directory.
+In theory, this file can be installed via `pip`, provided you don't rename it.
 
 You should consider [publishing](publishing) your extension to a package index like PyPI though.

docs/topics/creation.md

@@ -6,7 +6,8 @@ With Copier, creating a Salt extension project structure is easy:
 copier copy --trust https://github.com/salt-extensions/salt-extension-copier my-awesome-new-saltext
 ```
 
-You are then asked a set of questions that will shape the final project structure. They will be remembered for future updates in `.copier-answers.yml`.
+You are then asked a set of questions that will shape the final project structure.
+They will be remembered for future updates in `.copier-answers.yml`.
 
 :::{important}
 
@@ -19,10 +20,12 @@ so ensure you trust it!
 * [tasks and migrations][tasks-migrations]
 :::
 
+(first-steps-target)=
 ## First steps
 
 Many operations in your Salt extension project require to be run inside an initialized Git repository
-and a Python virtual environment with your project installed. Some `pre-commit` hooks might also create important files.
+and a Python virtual environment with your project installed. Some `pre-commit` hooks might also
+create important files.
 
 The following steps are therefore necessary to finish your project generation:
 
@@ -31,13 +34,14 @@ git init
 python -m venv venv
 source venv/bin/activate
 python -m pip install -e '.[tests,dev,docs]'
-python -m pre_commit install
+pre-commit install
 git add .
 git commit -m "Initial extension layout"  # Can fail, just add the changes and repeat
 ```
 
 ## Important considerations
 TODO
+
 ### Organization or individual
 
 [jinja-exts]: https://github.com/salt-extensions/salt-extension-copier/blob/main/jinja_extensions/saltext.py

docs/topics/documenting/building.md

@@ -0,0 +1,53 @@
+# Building documentation
+
+:::{important}
+Ensure you have already installed `nox`. If you followed the [first steps](first-steps-target), you should be fine.
+:::
+
+## Prerequisites
+On some systems (MacOS, WSL, some Linux distributions) building the docs requires the `enchant` library to be installed on your system.
+
+:::{tab} Linux/WSL
+```bash
+sudo apt-get install -y enchant
+```
+:::
+:::{tab} MacOS
+```bash
+brew install -y enchant
+```
+
+:::{important}
+On Apple Silicon, you might need to ensure your environment points to the correct library location:
+
+```bash
+export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib
+```
+:::
+
+## Build once
+If you just want to build your documentation:
+
+```bash
+nox -e docs
+```
+
+You can find the rendered docs in `docs/_build/html`.
+
+## Live preview
+While developing, it can help to have an automatically reloading preview of the rendered documentation.
+The following command renders the current documentation, starts an HTTP server, opens your default browser
+and watches the repository for changes.
+
+```bash
+nox -e docs-dev
+```
+
+:::{note}
+If you're building the documentation on a remote system, you need to override the
+host the HTTP server is listening to since it defaults to `localhost`:
+
+```bash
+nox -e docs-dev -- --host=1.2.3.4
+```
+:::

docs/topics/documenting/changelog.md

@@ -0,0 +1,32 @@
+# Keeping a changelog
+
+Your Saltext project includes scaffolding for keeping a changelog via [towncrier](https://towncrier.readthedocs.io/en/stable/).
+
+This changelog is rendered as part of the documentation.
+
+## Procedure
+Each time there is a user-facing change to your project, the patch should contain a corresponding news fragment.
+
+1. There should be an issue in the bug tracker that describes the context of the change.
+2. Before merging a PR, ensure there is an added news fragment in the `changelog` directory describing the change.
+3. Its file name should follow `<issue_number>.<resolution>.md`, where `resolution` is one of the following actions:
+
+    * `fixed`
+    * `added`
+    * `changed`
+    * `removed`
+    * `deprecated`
+    * `security`
+
+4. Its file contents are interpreted as Markdown.
+
+## Example
+
+A PR fixes an ungraceful crash when the `foo.bar` configuration value is missing.
+The author can create the news fragment as follows:
+
+```bash
+echo "Fixed a crash when 'foo.bar' is missing from the configuration" > changelog/23.fixed.md
+```
+
+This file should be submitted as part of the PR.

docs/topics/documenting/index.md

@@ -0,0 +1,14 @@
+# Documenting your Saltext
+
+Your Salt extension's documentation is rendered via [sphinx](https://www.sphinx-doc.org/en/master/index.html).
+
+[nox](https://nox.thea.codes/en/stable/) is used to set up a suitable environment and invoke `sphinx` correctly.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+building
+writing
+changelog
+```

docs/topics/documenting/writing.md

@@ -0,0 +1,108 @@
+# Writing documentation
+Your project's documentation sources are found in `docs`.
+
+## Markup language
+
+### `docs/*`
+You can write dedicated docs pages in both [MyST](https://myst-parser.readthedocs.io/en/stable/syntax/typography.html), a superset of Markdown,
+and [RST](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
+
+Yes, even in a mix.
+
+### Docstrings
+Docstrings in modules on the other hand must be written in RST.
+
+## Cross-references
+### Entities
+It's possible to cross-reference specific entities, which can improve the documentation's usability a lot.
+
+#### Modules
+Link to a complete module.
+
+Works for all modules that are present in the virtual environment, which includes Salt core ones.
+
+:::{tab} MyST
+```md
+{py:mod}`foo <saltext.foo.modules.foo_mod>`
+```
+:::
+:::{tab} RST
+```rst
+:py:mod:`foo <saltext.foo.modules.foo_mod>`
+```
+:::
+
+#### Functions
+Link to a specific function in a module.
+
+Works for all modules that are present in the virtual environment, which includes Salt core ones.
+
+:::{tab} MyST
+```md
+{py:func}`foo.bar <saltext.foo.modules.foo_mod.bar>`
+```
+:::
+:::{tab} RST
+```rst
+:py:func:`foo.bar <saltext.foo.modules.foo_mod.bar>`
+```
+:::
+
+#### Salt master configuration value
+Link to the documentation of a Salt master configuration value.
+
+:::{tab} MyST
+```md
+{conf_master}`ssh_minion_opts`
+```
+:::
+
+:::{tab} RST
+```rst
+:conf_master:`ssh_minion_opts`
+```
+:::
+
+#### Salt minion configuration value
+Link to the documentation of a Salt minion configuration value.
+
+:::{tab} MyST
+```md
+{conf_minion}`order_masters`
+```
+:::
+
+:::{tab} RST
+```rst
+:conf_minion:`order_masters`
+```
+:::
+
+### Arbitrary anchors
+You can define arbitrary anchors and reference them later in the same document or from a different document.
+
+:::{tab} MyST
+```md
+(my-custom-target)=
+# Something
+
+...
+
+Later in the file, or in another one:
+
+Please refer to [Something](my-custom-target)
+```
+:::
+:::{tab} RST
+```rst
+.. _my-custom-target:
+Something
+=========
+
+...
+
+Later in the file, or in another one:
+
+Please refer to :ref:`Something <my-custom-target>`
+```
+:::