Extend docs by links to cog docstrings

manual.rst

@@ -138,6 +138,10 @@ Special types of cogs are *supplies*, which generate new data, usually from sour
 and *drains*, which output the data outwards from the scope of the application. But they are special only
 conceptually, from the view of the Train and application any cog can generate new data or swallow it.
 
+Don't be surprised that various cogs are sorted in various modules not based on
+their type, but usually based on their conceptual relations, or their dependencies
+on external libraries (say JSON supply and drain, for example).
+
 Escapement
 ~~~~~~~~~~
 
@@ -328,7 +332,105 @@ This is wrapped into :py:func:`deadbeat.daemon.detach` call. You should also use
 :py:data:`deadbeat.daemon.daemon_base_config` insert to provide user with
 consistent daemon configuration.
 
+Cogs
+--------------------------------------------------------------------------------
+
+This is an overview of available cogs, for detailed documentation see linked
+in-code docstrings.  
+
+Supply cogs
+~~~~~~~~~~~
+
+Supply cogs are meant to be used as the starts of the geartrain, the driving
+shafts, watching for and feeding in the incoming data, possibly annotating
+it with unique id.
+
+:py:obj:`deadbeat.fs.FileWatcherSupply`
+    Watches the file and returns new lines as they appear (akin to *tail*).
+
+:py:obj:`deadbeat.fs.FilerSupply`
+    Watches the directory for new files and returns their contents (similar to
+    Maildir in function, so concurrent applications do not have to worry about
+    locking).
+
+Drain cogs
+~~~~~~~~~~
+
+Drain cogs are output shafts of the Deadbeat. They send or store the transformed
+or generated data into some of the output channel, also taking care to inform
+other cogs that particular piece of data has been successfully processed.
+
+:py:obj:`deadbeat.fs.LineFileDrain`
+    Outputs the data as lines into the text file.
+
+:py:obj:`deadbeat.fs.FilerDrain`
+    Outputs the data as a new file into the directory (similar to Maildir in
+    function, so concurrent applications do not have to worry about locking).
+
+Parsing cogs
+~~~~~~~~~~~~
+
+Cogs meant for translating input/wire format into structured form.
+
+:py:obj:`deadbeat.text.CSVParse`
+    Parses the data as CSV formatted line.
+
+:py:obj:`deadbeat.text.JSONParse`
+    Parses the data from JSON formatted document.
+    
+:py:obj:`deadbeat.text.RegexpLexicon`, :py:obj:`deadbeat.text.LinearRegexpLexicon`
+    Parses the data by means of the set of linear expressions. 
+
+Marshalling cogs
+~~~~~~~~~~~~~~~~
+
+Complements to parsing cogs; cogs meant to convert structured data into
+output/wire format.
+
+:py:obj:`deadbeat.text.CSVMarshall`
+    Marshalls the data into CSV formatted lines.
+
+:py:obj:`deadbeat.text.JSONMarshall`
+    Marshalls the data into JSON formatted document.
+
+:py:obj:`deadbeat.text.JinjaMarshall`
+    Marshalls the data according to Jinja template.
+
+Conversion cogs
+~~~~~~~~~~~~~~~
+
+Cogs, helping to cast, normalize or tweak particular pieces of the data.
+
+:py:obj:`deadbeat.twist.Normalize`
+    Validates and converts the data according to :py:obj:`typedcols.TypedDict`.
+
+:py:obj:`deadbeat.ip.IdeaAnonymise`
+    Anonymises the IP addresses (into parent networks) for data in IDEA_ format.
+
+Enrichment cogs
+~~~~~~~~~~~~~~~
+
+Cogs, adding new pieces of data.
+
+:py:obj:`deadbeat.text.ConstLexicon`
+    Enriches the data from dict, indexed by some particular data piece.
+
+:py:obj:`deadbeat.dns.IPtoPTR`
+    Enriches the data by resolving the IP addresses.
+
+Processing cogs
+~~~~~~~~~~~~~~~
+
+Cogs, which may split, merge or swallow the data.
+
+:py:obj:`deadbeat.ip.FilterBase`
+    Base abstract class for deriving event data filters.
+
+:py:obj:`deadbeat.ip.IPFilter`
+    Filters the data events based on IP address ranges.
 
+:py:obj:`deadbeat.twist.WindowContextMgr`
+    Base abstract class for deriving time window context based cogs.
 
 Indices and tables
 --------------------------------------------------------------------------------