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.).