From 57fe188819ef9e614e9d9641ddfd2b1140c713bb Mon Sep 17 00:00:00 2001 From: Victor Lin <13424970+victorlin@users.noreply.github.com> Date: Tue, 25 Jul 2023 11:02:46 -0700 Subject: [PATCH] Use sections for each recommendation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 59 ++++++++++++++----------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/src/reference/snakemake-style-guide.rst b/src/reference/snakemake-style-guide.rst index bc8f56e7..6fb1bd3f 100644 --- a/src/reference/snakemake-style-guide.rst +++ b/src/reference/snakemake-style-guide.rst @@ -5,37 +5,44 @@ Snakemake style guide When in doubt, refer to `Snakemake's own best practices guide `__. -- 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 `__ - that can provide alternate commands for generating required files. - This approach does not work with references to rule outputs, - though (`see ncov PR - 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 + `__ + that can provide alternate commands for generating required files. + This approach does not work with references to rule outputs, though + (`see ncov PR 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.).