Improve the documentation. (#61)

Author: tobiasraabe

README.rst

@@ -32,8 +32,7 @@
 .. end-badges
 
 
-Features
---------
+.. start-features
 
 In its highest aspirations, pytask tries to be pytest as a build system. It's main
 purpose is to facilitate reproducible research by automating workflows in research
@@ -63,6 +62,8 @@ projects. Its features include:
   <https://pytask-dev.readthedocs.io/en/latest/tutorials/how_to_use_plugins.html>`_ how
   you can use plugins.
 
+.. end-features
+
 
 Why do I need a build system?
 -----------------------------

docs/changes.rst

@@ -12,6 +12,7 @@ all releases are available on `Anaconda.org <https://anaconda.org/pytask/pytask>
 - :gh:`55` implements miscellaneous fixes to improve error message, tests and coverage.
 - :gh:`59` adds a tutorial on using plugins and features plugins more prominently.
 - :gh:`60` adds the MIT license to the project and mentions pytest and its developers.
+- :gh:`61` adds many changes to the documentation.
 - :gh:`65` adds versioneer to pytask and :gh:`66` corrects the coverage reports which
   were deflated due to the new files.
 - :gh:`67` prepares pytask to be published on PyPI.

docs/explanations/why_another_build_system.rst renamed to docs/explanations/build_systems.rst

@@ -1,5 +1,8 @@
+Build Systems
+=============
+
 Why another build system?
-=========================
+-------------------------
 
 There are a lot of build systems out there with existing communities who accumulated a
 lot of experience over time. So why bother creating another build system?
@@ -96,17 +99,3 @@ Pros
 Cons
 
 - Seems to have no plugin system.
-
-
-`cook <https://github.com/jachris/cook>`_
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Pros
-
-- Still simple, maybe useful for some quick inspirations.
-
-Cons
-
-- Development is paused.
-- Designed for compiling software.
-- No plugin system, but extensible interfaces.

docs/explanations/design.rst

@@ -8,6 +8,5 @@ systems in general as well as its design.
    :maxdepth: 1
 
    why_do_i_need_a_build_system
-   why_another_build_system
-   design
+   build_systems
    pluggy

docs/explanations/index.rst

@@ -7,8 +7,8 @@ TL;DR
 Research projects consists of complex workflows which handle data, employ models, and
 produce figures, tables, and reports.
 
-Making sure that all steps of the analysis are up-to-date should not be done by hand
-since this process is error-prone and time-consuming.
+Ensuring that all steps of the analysis are up-to-date should not be done by hand since
+this process is error-prone and time-consuming.
 
 Build systems like pytask provide an easy interface for researchers to express the
 relationships among the tasks in a research project and conveniently manage the

docs/explanations/why_do_i_need_a_build_system.rst

@@ -6,13 +6,26 @@ pytask
    :end-before: end-badges
 
 
+Features
+--------
+
+.. include:: ../README.rst
+   :start-after: start-features
+   :end-before: end-features
+
+
+Installation
+------------
+
 .. include:: ../README.rst
    :start-after: start-installation
    :end-before: end-installation
 
 
-The documentation is build upon four pillars:
+Documentation
+-------------
 
+If you want to know more about pytask, dive into one the following topics.
 
 .. panels::
     :container: container pb-4
@@ -28,8 +41,7 @@ The documentation is build upon four pillars:
         :text: Tutorials
         :classes: stretched-link font-weight-bold
 
-    Tutorials help you to get started with pytask, explain the interface and basic
-    capabilities.
+    Tutorials help you to get started with pytask and how you manage your first project.
 
     ---
     :img-top: _static/images/book.svg
@@ -39,8 +51,8 @@ The documentation is build upon four pillars:
         :text: How-to Guides
         :classes: stretched-link font-weight-bold
 
-    How-to guides are designed to provide detailed instructions for very specific and
-    advanced tasks.
+    How-to guides provide instructions for very specific and advanced tasks and document
+    best-practices.
 
     ---
     :img-top: _static/images/books.svg
@@ -50,8 +62,7 @@ The documentation is build upon four pillars:
         :text: Explanations
         :classes: stretched-link font-weight-bold
 
-    Explanations give detailed information on key topics and concepts which underlie the
-    package.
+    Explanations deal with key topics and concepts which underlie the package.
 
     ---
     :img-top: _static/images/coding.svg

docs/index.rst

@@ -24,3 +24,12 @@ pytask.mark.parametrize
 
 .. autofunction:: _pytask.parametrize.parametrize
    :noindex:
+
+
+pytask.mark.try_first
+---------------------
+
+.. function:: try_first
+    :noindex:
+
+    This

docs/reference_guides/marks.rst

@@ -2,25 +2,26 @@ channels:
   - conda-forge
 
 dependencies:
-  - python=3.8
+  - python >= 3.6
   - pip
   - furo
   - ipython
+  - nbsphinx
   - sphinx
-  - sphinx-copybutton
-  - sphinx-autodoc-typehints
   - sphinx-autoapi
+  - sphinx-autodoc-typehints
   - sphinx-click
+  - sphinx-copybutton
   - sphinx-panels
 
   # Package dependencies necessary for sphinx-click
-  - attrs
+  - attrs >=17.4.0
   - click
   - click-default-group
   - networkx
-  - pexpect
   - pluggy
-  - pony >= 0.7.13
+  - pony >=0.7.13
+  - pexpect
 
   - pip:
     - -e ../

docs/rtd_environment.yml

@@ -1,25 +1,38 @@
 How to debug
 ============
 
-To facilitate debugging, pytask offers two command-line options.
+The debug mode is one of pytask's biggest strength. Whenever you encounter an error in
+one of your tasks, jump right into the code and inspect the cause of the exception.
 
-.. tip::
+Quick and easy feedback through a debugger is immensely valuable because it helps you to
+be more productive and gain more confidence in your code.
 
-    Instead of Python's :mod:`pdb`, use `pdb++ <https://github.com/pdbpp/pdbpp>`_ which
-    is more convenient, colorful has some useful features like the `sticky mode
-    <https://github.com/pdbpp/pdbpp#sticky-mode>`_.
+To facilitate debugging, pytask offers two command-line options.
 
 
 Debugging
 ---------
 
+Running
+
 .. code-block:: console
 
     $ pytask --pdb
 
 enables the post-mortem debugger. Whenever an exception is raised inside a task, the
 prompt will enter the debugger enabling you to discover the source of the exception.
 
+.. seealso::
+
+    :doc:`A following tutorial <how_to_select_tasks>` shows you how to run only one or a
+    subset of tasks which can be combined with the debug mode.
+
+.. tip::
+
+    Instead of Python's :mod:`pdb`, use `pdb++ <https://github.com/pdbpp/pdbpp>`_ which
+    is more convenient, colorful has some useful features like the `sticky mode
+    <https://github.com/pdbpp/pdbpp#sticky-mode>`_.
+
 
 Tracing
 -------