Use sections for each recommendation

This is consistent with the existing documentation style guide and a
similar Snakemake style guide¹ written by @tsibley.

This also allows for the addition of a table of contents, which is done
here.

I looked into making the section links future-proof to wording changes,
however could not find a good solution. The closest is using :ref: roles
which adds separately defined links to to the section titles, but those
links aren't used by the TOC or header links themselves.

¹ https://github.com/blab/styleguide/blob/6aa5d7aa42acfa97e57a5ee05a4175f158502cac/nextstrain-builds.md

src/reference/snakemake-style-guide.rst

@@ -5,37 +5,44 @@ Snakemake style guide
 When in doubt, refer to `Snakemake's own best practices
 guide <https://snakemake.readthedocs.io/en/stable/snakefiles/best_practices.html>`__.
 
--  Avoid ``run`` blocks; implement custom Python in scripts called in a
-   ``shell`` block.
+.. contents:: Table of Contents
+   :local:
 
-   -  Code in ``run`` blocks is less reusable. Anything we write once,
-      we're likely to want to reuse later.
+Avoid ``run`` blocks
+====================
 
-   -  ``run`` blocks can be challenging to debug.
+Instead, implement custom Python in scripts called in a ``shell`` block.
 
-   -  ``run`` blocks do not run in rule-specific conda environments,
-      forcing the user to manually install into their environment any
-      dependencies that could have been in a conda environment file.
+-  Code in ``run`` blocks is less reusable. Anything we write once,
+   we're likely to want to reuse later.
 
--  Define ``input`` paths with literal path strings instead of ``rule``
-   variables.
+-  ``run`` blocks can be challenging to debug.
 
-   -  Literal paths are easier to read and interpret, avoiding the need
-      to trace back through a workflow to an earlier rule to see the
-      path associated with a rule output.
+-  ``run`` blocks do not run in rule-specific conda environments,
+   forcing the user to manually install into their environment any
+   dependencies that could have been in a conda environment file.
 
-   -  Literal paths also allow workflows to be rewired with custom rules
-      that are injected at runtime. For example, `the ncov workflow
-      allows users to define their own
-      rules <https://docs.nextstrain.org/projects/ncov/en/latest/reference/configuration.html#custom-rules>`__
-      that can provide alternate commands for generating required files.
-      This approach does not work with references to rule outputs,
-      though (`see ncov PR
-      877 <https://github.com/nextstrain/ncov/pull/877>`__, for an
-      example).
+Define ``input`` paths with literal path strings
+================================================
 
--  Avoid the ``message`` rule attribute.
+Do this instead of using ``rule`` variables.
 
-   -  When the ``message`` attribute is defined, Snakemake suppresses
-      other critical details that otherwise get displayed by default
-      (e.g., job id, rule name, input, output, etc.).
+-  Literal paths are easier to read and interpret, avoiding the need to
+   trace back through a workflow to an earlier rule to see the path
+   associated with a rule output.
+
+-  Literal paths also allow workflows to be rewired with custom rules
+   that are injected at runtime. For example, `the ncov workflow allows
+   users to define their own rules
+   <https://docs.nextstrain.org/projects/ncov/en/latest/reference/configuration.html#custom-rules>`__
+   that can provide alternate commands for generating required files.
+   This approach does not work with references to rule outputs, though
+   (`see ncov PR 877 <https://github.com/nextstrain/ncov/pull/877>`__,
+   for an example).
+
+Avoid the ``message`` rule attribute
+====================================
+
+-  When the ``message`` attribute is defined, Snakemake suppresses other
+   critical details that otherwise get displayed by default (e.g., job
+   id, rule name, input, output, etc.).