Documentation in linotype consists of a tree of ‘items’ of which there are
currently two types, text and definitions. Every item can contain other
items which are indented relative to the parent item. The
linotype.Item class is used to create a root-level item, and every
linotype.Item object has public methods for creating new sub-items
which in turn return a new
linotype.Item object accepts a
instance which is used to define how items are formatted in the text output.
Every item can optionally be assigned an ID that can be referenced in the
Sphinx documentation or when formatting the text output. Here is an example
that prints a simple help message:
1 2 3 4 5 6 7 8 9 10 11 12
from linotype import Item def help_message(): root_item = Item() usage = root_item.add_text("Usage:") usage.add_def( "todo", "[global_options] command [command_args]", "") return root_item print(help_message().format())
Line wrapping, indentation, alignment and markup are all applied automatically
according to attributes set in the
linotype.Formatter object, so all
text is passed into linotype as unformatted, single-line strings.
Additionally, inline ‘strong’ and ‘emphasized’ markup can be applied manually
using the reStructuredText syntax:
This text is **strong**. This text is *emphasized*.
To use linotype with Sphinx, you must first add ‘linotype.ext’ to the list of Sphinx extensions in the conf.py file for your project:
extensions = ["linotype.ext"]
The documentation can be imported into your Sphinx documentation using the ‘linotype’ directive. It accepts the following options:
- The name of the function which returns a
- The name of the module containing the function.
- The path of the python file containing the function.
- The ID of an item in the tree returned by the function. The output is restricted to just this item and its children.
- Display the item’s children but not the item itself.
- Do not automatically apply ‘strong’ and ‘emphasized’ formatting to the output.
- Do not parse ‘strong’ and ‘emphasized’ inline markup.
The options :module: and :filepath: are mutually exclusive. The options :function: and either :module: or :filepath: are required.
Using the ‘linotype’ directive, you can extend or replace parts of your help message. This allows you to add new content that appears in your Sphinx documentation but not in your text output. This is done on a per-item basis using a reStructuredText definition list, where the term is the ID of an item and the definition is the new content to use. You can also add classifiers, which change how the new content is incorporated.
These classifiers affect where the content is added:
- The new content is added after the existing content. This is the default.
- The new content is added before the existing content.
- The new content replaces the existing content.
These classifiers affect how markup is applied to the content:
- Markup is applied to the text automatically, and ‘strong’ and ‘emphasized’ inline markup can be applied manually. This is the default.
- Markup is not applied automatically, but any reStructuredText body or inline elements can be used. The new content starts in a separate paragraph.
Here is an example of a Sphinx source file using the directive:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
.. linotype:: :module: todo.cli :function: help_message add This content is added after the existing content for the item with the ID 'add.' Markup is applied automatically. add : @before : @rst This content is added before the existing content for the item with the ID 'add.' reStrcturedText elements can be used. check : @replace This content replaces the existing content for the item with the ID 'check.' Markup is applied automatically.