DOC: Improved documentation.

src/doc/conf.py

@@ -53,6 +53,7 @@ extensions = [
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',     # For Google style docstrings
+    "sphinx.ext.todo",
     "recommonmark",            # For markdown files.
     "sphinx_rtd_theme",
 ]

src/doc/converters.rst

@@ -8,10 +8,6 @@ existing StructureElements, Converters create a tree of StructureElements.
 .. image:: img/converter.png
   :height: 170
 
-The ``cfood.yml`` definition also describes which
-Converters shall be used to treat the generated child StructureElements. The
-definition therefore itself also defines a tree.
-
 Each StructureElement in the tree has a set of properties, organized as
 key-value pairs.
 Some of those properties are specified by the type of StructureElement. For example,
@@ -19,15 +15,18 @@ a file could have the file name as property: ``'filename': myfile.dat``.
 Converters may define additional functions that create further values. For
 example, a regular expression could be used to get a date from a file name.
 
+CFood definition
+++++++++++++++++
 
-A converter is defined via a yml file or part of it. The definition states
-what kind of StructureElement it treats (typically one).
-Also, it defines how children of the current StructureElement are
-created and what Converters shall be used to treat those.
+Converter application to data is specified via a tree-like yml file (called ``cfood.yml``, by
+convention).  The yml file specifies which Converters shall be used on which StructureElements, and
+how to treat the generated *child* StructureElements.
 
 The yaml definition may look like this:
 
-TODO: outdated, see cfood-schema.yml
+.. todo::
+
+  This is outdated, see ``cfood-schema.yml`` for the current specification of a ``cfood.yml``.
 
 .. code-block:: yaml
 
@@ -47,13 +46,16 @@ TODO: outdated, see cfood-schema.yml
         subtree:
             (...)
 
-The **<NodeName>** is a description of what it represents (e.g.
-'experiment-folder') and is used as identifier.
+The **<NodeName>** is a description of what the current block represents (e.g.
+``experiment-folder``) and is used as an identifier.
 
 **<type>** selects the converter that is going to be matched against the current structure
 element. If the structure element matches (this is a combination of a typecheck and a detailed
-match, see :py:class:`~caoscrawler.converters.Converter` for details) the converter is used
-to generate records (see :py:meth:`~caoscrawler.converters.Converter.create_records`) and to possibly process a subtree, as defined by the function :func:`caoscrawler.converters.create_children`.
+match, see the :py:class:`~caoscrawler.converters.Converter` source documentation for details), the
+converter will:
+
+- generate records (with :py:meth:`~caoscrawler.converters.Converter.create_records`)
+- possibly process a subtree (with :py:meth:`caoscrawler.converters.Converter.create_children`)
 
 **match** *TODO*
 

src/doc/tutorials/parameterfile.rst

@@ -88,6 +88,10 @@ regular expressions do:
 We can use the groups from the regular expressions that are used for matching.
 In our example, we use the "value" group to assign the "frequency" value to the "Experiment".
 
+.. note::
+
+  For more information on the ``cfood.yml`` specification, read on in the chapter :ref:`Converters`.
+
 A fully grown CFood
 -------------------
 
@@ -148,4 +152,6 @@ the CFood file is in the current working directory):
 
    caosdb-crawler -s update -i identifiables.yml cfood.yml .
 
+.. note::
 
+   ``caosdb-crawler`` currently only works with cfoods which have a directory as top level element.