Add more docs

docs/api.rst

@@ -6,17 +6,15 @@ Python API
 **Sphinx-Needs** provides an open API for other Sphinx-extensions to provide specific need-types, create needs or
 make usage of the filter possibilities.
 
-The API allows the injection of extra configuration into it. The API does not support the overall manipulation (e.g remove need types)
+The API allows the injection of extra configuration, but
+does not support manipulation of it (e.g remove need types),
 to keep the final configuration transparent for the Sphinx project authors.
 
-For some implementation ideas, take a look into the Sphinx extension
-`Sphinx-Test-Reports <https://sphinx-test-reports.readthedocs.io/en/latest/>`_ and its
-`source code <https://github.com/useblocks/sphinx-test-reports/blob/master/sphinxcontrib/test_reports/test_reports.py>`_.
-
 .. _api_configuration:
 
 Configuration
 -------------
+
 .. automodule:: sphinx_needs.api.configuration
    :members:
 
@@ -25,12 +23,14 @@ Configuration
 
 Need
 ----
+
 .. automodule:: sphinx_needs.api.need
    :members:
 
 
 Exceptions
 ----------
+
 .. automodule:: sphinx_needs.api.exceptions
    :members:
 
@@ -43,6 +43,9 @@ Data
 Views
 -----
 
+These views are returned by certain functions, and injected into filters,
+but should not be instantiated directly.
+
 .. automodule:: sphinx_needs.views
    :members:
    :undoc-members:

docs/tutorial.rst

@@ -11,7 +11,6 @@ We will create need items, link them together, visualize the relationships betwe
     :root_id: T_CAR
     :config: tutorial
     :show_link_names:
-    :show_filters:
     :border_color:
         [status == 'open']:FF0000, 
         [status == 'in progress']:0000FF, 
@@ -22,6 +21,17 @@ We will create need items, link them together, visualize the relationships betwe
     This tutorial assumes that you have already :ref:`installed sphinx-needs <installation>`,
     and that you have a basic understanding of how to use :external+sphinx:doc:`Sphinx <index>` and :external+sphinx:ref:`reStructuredText <rst-primer>`.
 
+Need Lifecycle
+--------------
+
+Within a sphinx build, a primary role of sphinx-needs is to manage the lifecycle of need items:
+
+1. **Collect**: During the read phase, need items are collected from the source files and configured external sources.
+2. **Resolve**: After the read phase, the need items are post-processed to resolve dynamic fields and links, etc, then frozen.
+3. **Analyse**: During the write phase, various directives/roles are available to reference, query, and output analysis of the needs.
+4. **Render**: During the write phase, the need items are rendered into the output format, such as HTML or PDF.
+5. **Validate**: During the final phase, the need items can be validated against configured checks.
+
 Creating need items
 -------------------