Document doit extensions and improve searchability

doc/cmd-run.rst

@@ -42,17 +42,29 @@ dodo file
 ----------
 
 By default all commands are relative to ``dodo.py`` in the current folder.
-You can specify a different *dodo* file containing task with the flag ``-f``.
+You can specify a different *dodo* file containing tasks with the ``-f`` flag.
 This flag is valid for all sub-commands.
 
+.. option:: -f FILE, --file FILE
+
+   Specify the dodo file (default: ``dodo.py``)
+
 
 .. code-block:: console
 
     $ doit -f release.py
 
 
-*doit* can seek for the ``dodo.py`` file on parent folders if the option
-``--seek-file`` is specified.
+*doit* can seek for the ``dodo.py`` file in parent folders if the
+``--seek-file`` option is specified.
+
+.. option:: --seek-file
+
+   Seek for dodo file in parent directories
+
+.. note::
+   The ``--seek-file`` option can also be set via the :envvar:`DOIT_SEEK_FILE`
+   environment variable.
 
 
 as an executable file

doc/configuration.rst

@@ -108,14 +108,16 @@ the task name under `tool.doit.tasks`:
    duration = 12
 
 
+.. _doit.cfg:
+
 doit.cfg
 --------
 
 `doit` also supports an INI style configuration file
 (see `configparser <https://docs.python.org/3/library/configparser.html>`_).
 Note: key/value entries can be separated only by the equal sign `=`.
 
-If a file name `doit.cfg` is present in the current working directory,
+If a file name :file:`doit.cfg` is present in the current working directory,
 it is processed. It supports 4 kind of sections:
 
 - a `GLOBAL` section

doc/dependencies.rst

@@ -397,6 +397,12 @@ the calculation of dependencies to another task.
 The task calculating dependencies must have a python-action returning a
 dictionary with `file_dep`, `task_dep`, `uptodate` or another `calc_dep`.
 
+.. warning::
+   The returned values must be JSON-encodable since `doit` uses
+   :ref:`saved values <result_dep>` to pass the result of the calculation task.
+   For example, returning ``pathlib.Path`` objects in ``file_dep`` will cause failures.
+   Convert such objects to strings before returning them.
+
 .. note::
    An alternative way (and often easier) to have task attributes that
    rely on other tasks execution is to use :ref:`delayed tasks <delayed-task-creation>`.

doc/related.rst

@@ -8,7 +8,24 @@
 Related Projects
 ================
 
-Build tools & task runners:
+doit extensions & plugins
+--------------------------
+
+Backend & Reporting Extensions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ - `doit-redis <https://github.com/saimn/doit-redis>`_ - Redis backend for doit
+ - `doit-report <https://github.com/saimn/doit-report>`_ - Custom reporters for doit
+
+Task Creation Helpers
+^^^^^^^^^^^^^^^^^^^^^
+
+ - `doit-api <https://smarie.github.io/python-doit-api/>`_ - Explicit API with IDE autocompletion and documentation for easier task creation
+ - `letsdoit <https://bitbucket.org/takluyver/letsdoit>`_ - Custom task definition framework
+
+
+Build tools & task runners
+---------------------------
 
  - `make <https://www.gnu.org/software/make/>`_
  - `just <https://github.com/casey/just>`_ - command runner (no dependency tracking)

doc/task-creation.rst

@@ -117,8 +117,9 @@ callable from any object that contains this attribute.
 
 .. literalinclude:: samples/custom_task_def.py
 
-The `project letsdoit <https://bitbucket.org/takluyver/letsdoit>`_
-has some real-world implementations.
+The projects `letsdoit <https://bitbucket.org/takluyver/letsdoit>`_
+and `doit-api <https://smarie.github.io/python-doit-api/>`_
+have some real-world implementations.
 
 For simple examples to help you create your own check this
 `blog post <http://blog.schettino72.net/posts/doit-task-creation.html>`_.