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

ford.md_admonition.ADMONITION_TYPE = {'bug': 'danger', 'history': 'history', 'note': 'info', 'todo': 'success', 'warning': 'warning'}

Mapping of Ford note types to markdown’s admonition types

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