ford.md_admonition module#

Admonition Preprocessor#

Markdown preprocessor for dealing with FORD style admonitions. See Notes and Warning Boxes for details on using these in Ford docs.

A preprocessor, AdmonitionPreprocessor, converts Ford style @note into something that the existing markdown admonition extension can handle. This is mostly a matter of making sure the note body is indented correctly. The conversion to HTML is done with a customised processor, FordAdmonitionProcessor

class ford.md_admonition.AdmonitionExtension(**kwargs)#

Bases: Extension

Admonition extension for Python-Markdown.

extendMarkdown(md)#

Add Admonition to Markdown instance.

class ford.md_admonition.AdmonitionPreprocessor(md=None)#

Bases: Preprocessor

Markdown preprocessor for dealing with FORD style admonitions.

This preprocessor converts the FORD syntax for admonitions to the markdown admonition syntax.

A FORD admonition starts with @<type>, where <type> is one of: note, warning, todo, bug, or history. An admonition ends at (in this order of preference):

  1. @end<type>, where <type> must match the start marker

  2. an empty line

  3. a new note (@<type>)

  4. the end of the documentation lines

The admonitions are converted to the markdown syntax, i.e. @note Note, followed by an indented block. Possible end markers are removed, as well as empty lines if they mark the end of an admonition.

ADMONITION_RE: ClassVar[Pattern] = re.compile('(?P<indent>\\s*)\n        @(?P<type>note|warning|todo|bug|history)\n        (?P<posttxt>.*)\n        ', re.IGNORECASE|re.VERBOSE)#
class Admonition(type, start_idx, end_idx=-1)#

Bases: object

A single admonition block in the text.

end_idx: int = -1#

Line index where admonition ends

start_idx: int#

Line index of start marker

type: str#

Admonition type (note, bug, and so on)

END_RE: ClassVar[Pattern] = re.compile('\\s*@end(?P<type>note|warning|todo|bug|history)\n        \\s*(?P<posttxt>.*)?', re.IGNORECASE|re.VERBOSE)#
INDENT: ClassVar[str] = '    '#
INDENT_SIZE: ClassVar[int] = 4#
admonitions: List[Admonition] = []#
run(lines)#

Each subclass of Preprocessor should override the run method, which takes the document as a list of strings split by newlines and returns the (possibly modified) list of lines.

Return type:

List[str]

class ford.md_admonition.FordAdmonitionProcessor(parser)#

Bases: AdmonitionProcessor

Customised version of the Python markdown extension.

Uses our CSS class names for each specific note type.

CLASSNAME = 'alert'#
CLASSNAME_TITLE = 'alert-title h4'#
RE = re.compile('(?:^|\\n)@note ?(?P<klass>[\\w\\-]+) *(?:\\n|$)')#
get_class_and_title(match)#

Get the CSS class and title for this admonition

Title is the note class, while the CSS class is looked up in the list of note types (ADMONITION_TYPE)

exception ford.md_admonition.FordMarkdownError(message, line_number, lines, start, end, context=4)#

Bases: RuntimeError

Format an error when processing markdown, giving some context