Docstring rendering

The are five different parts in the pipeline of sectiondoc docstring rendering.


The rendering Style maps the objects types provided by autodoc to DocRender factory instances which are responsible for rendering the provided docstring.

The DocRender

The DocRender is responsible for doing the actual work. At initialization the class receives a dictionary mapping section titles to a tuple containing a rendering function and (optionally) section item parsing and rendering classes. The actual rendering starts by executing parse() to detect sections in the docstring. For each section that is discovered the _render() is called with the name of the discovered section to further dispatch processing to the associated section rendering function. If an associated function to the section does not exist the default is to use rubric().

Section rendering function

The rendering fuctions will use the utility methods of the the DocRender instance to extract the section block. Depedending on the implementation extract_paragraph() is called to return the paragraph for further processing or extract_items() is called to return the list of Item instances. When a list of Item is collected the section the rendering function will produce the updated rst docstring using the appropriate Renderer.


Item instances contain the term, classfier(s) and definition information of items in a section. Each Item type knows how to parse a set of lines grouping and filtering the information ready to be rendered into sphinx friendly rst.


The Renderer is used by the section renderer functions to render a previously contructed Item into sphinx friently rst.