Start guides for best-practices. (#49)

Author: tobiasraabe

docs/changes.rst

@@ -12,6 +12,7 @@ all releases are available on `Anaconda.org <https://anaconda.org/pytask/pytask>
 - :gh:`45` adds the option to stop execution after a number of tasks has failed. Closes
   :gh:`44`.
 - :gh:`47` reduce node names in error messages while resolving dependencies.
+- :gh:`49` starts a style guide for pytask.
 - :gh:`50` implements correct usage of singular and plural in collection logs.
 - :gh:`51` allows to invoke pytask through the Python interpreter with ``python -m
   pytask`` which will add the current path to ``sys.path``.
@@ -28,7 +29,6 @@ all releases are available on `Anaconda.org <https://anaconda.org/pytask/pytask>
 - :gh:`42` ensures that lists with one element and dictionaries with only a zero key as
   input for ``@pytask.mark.depends_on`` and ``@pytask.mark.produces`` are preserved as a
   dictionary inside the function.
-- :gh:`43` releases v0.0.10.
 
 
 0.0.9 - 2020-10-28

docs/how_to_guides/bp_organization.rst

@@ -0,0 +1,30 @@
+Organization
+============
+
+How to contribute
+-----------------
+
+Any contribution is highly appreciated. Feel free to continue a discussion in `an
+existing issue <https://github.com/pytask-dev/pytask/issues>`_ ticket or `file a new
+ticket <https://github.com/pytask-dev/pytask/issues/new/choose>`_ if, for example, some
+of the following applies to you:
+
+- You have a question regarding an existing guide or feel a guide needs clarification.
+
+- You want to share your own experience with the suggestions provided in a guide.
+
+- You want to extend the collection by providing another best-practices guide.
+
+
+Structure of guides
+-------------------
+
+1. Each guide should start with a description of the scope of the guide. At best, guides
+   deal with one thing only. If guides deal with higher-level topics, they should link
+   to lower-level guides instead of trying to explain too much.
+
+2. The second section is a TL;DR (too long; did not read) which provides a short summary
+   of the guide and its (five) most important messages.
+
+3. The third section provides the advice in detail. This section must be well
+   structured, concise, and easy to understand. Each tip is associated with an example.

docs/how_to_guides/bp_structure_of_task_files.rst

@@ -0,0 +1,30 @@
+Structure of task files
+=======================
+
+This section provides best-practices on how to structure task files.
+
+
+TL;DR
+-----
+
+- A task function should be the first function in a task module and serve as an
+  entry-point to the whole module.
+
+- There might be multiple task functions in a task module, but it is recommended to
+  split modules once they become too large.
+
+- The task function is mainly responsible for handling IO operations like loading and
+  saving files and calling Python functions on the task's inputs. IO should not be
+  handled in other functions since it introduces side-effects.
+
+- All other functions in the module are private functions used to accomplish only this
+  specific task. The functions should be pure, meaning without side-effects.
+
+- Functions used to accomplish tasks in multiple task modules should have their own
+  module.
+
+
+.. seealso::
+
+    The advice above may remind readers of "deep modules", a term coined by John
+    Ousterhout and described in "A Philosophy of Software Design".

docs/how_to_guides/index.rst

@@ -1,13 +1,40 @@
 How-to Guides
 =============
 
-How-to guides provide detailed explanations on how to accomplish specific tasks with
-pytask.
+This section contains two collections of documents.
 
 
+How-to Guides
+-------------
+
+The first collection of how-to guides provide detailed explanations on how to accomplish
+specific tasks with pytask.
+
 .. toctree::
    :maxdepth: 1
 
    how_to_write_a_plugin
    how_to_extend_parametrizations
    how_to_influence_build_order
+
+
+Best-Practices
+--------------
+
+The second collection comprises best-practices guides for pytask. The guides combine
+experience with pytask and build systems in general, research projects, and software
+engineering to provide useful and easily understandable instructions.
+
+Contributions in any form - additions, comments, own experiences, request for
+clarifications - are highly appreciated. Please continue a discussion in `an existing
+issue <https://github.com/pytask-dev/pytask/issues>`_ ticket or `file a new ticket
+<https://github.com/pytask-dev/pytask/issues/new/choose>`_.
+
+For more information on how best-practices guides are organized and how to contribute,
+see the section on :doc:`bp_organization`.
+
+.. toctree::
+   :maxdepth: 1
+
+   bp_organization
+   bp_structure_of_task_files