linuxdoc.manKernelDoc module

kernel-doc-man

Implementation of the kernel-doc-man builder.

User documentation see man pages from kernel-doc comments.

class linuxdoc.manKernelDoc.KernelDocMan(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

optional_arguments = 0

Number of optional arguments after the required arguments.

required_arguments = 1

Number of required directive arguments.

run()

class linuxdoc.manKernelDoc.KernelDocManBuilder(app: Sphinx, env: BuildEnvironment)

Bases: ManualPageBuilder

Builds groff output in manual page format.

finish()

Finish the building process.

The default implementation does nothing.

format: str = 'man'

The builder’s output format, or ‘’ if no document output is produced. This is commonly the file extension, e.g. “html”, though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

get_partial_document(children)

init()

Load necessary templates and perform initialization. The default implementation does nothing.

is_manpage(node)

name: str = 'kernel-doc-man'

The builder’s name. This is the value used to select builders on the command line.

prepare_writing(docnames)

A place where you can add logic before write_doc() is run

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

write(*ignored)

Write builder specific output files.

write_doc(docname, doctree)

Where you actually write something to the filesystem.

class linuxdoc.manKernelDoc.Section2Manpage(document, startnode=None)

Bases: Transform

Transforms a section tree into an manpage tree.

The structural layout of a man-page differs from the one produced, by the kernel-doc parser. The kernel-doc parser produce reST which fits to normal documentation, e.g. the declaration of a function in reST is like.

 user_function
 =============

 .. c:function:: int user_function(int a)

    The *purpose* description.

    :param int a:
        Parameter a description

Description
===========

lorem ipsum ..

Return
======

Returns first argument

On the other side, in man-pages it is common (see man man-pages) to print the purpose line in the “NAME” section, function’s prototype in the “SYNOPSIS” section and the parameter description in the “OPTIONS” section:

NAME
       user_function -- The *purpose* description.

SYNOPSIS
        int user_function(int a)

OPTIONS
        a

DESCRIPTION
        lorem ipsum

RETURN VALUE
        Returns first argument

apply(**kwargs)

Override to apply the transform to the document tree.

isolate_sections(sec_by_title)

isolate_synopsis(sec_by_title)

manTitleOrder = ['SYNOPSIS', 'CONFIGURATION', 'DESCRIPTION', 'OPTIONS', 'EXIT STATUS', 'RETURN VALUE', 'ERRORS', 'ENVIRONMENT', 'FILES', 'VERSIONS', 'ATTRIBUTES', 'CONFORMING TO', 'NOTES', 'BUGS', 'EXAMPLE', 'SEE ALSO']

manTitles = [(re.compile('^SYNOPSIS|^DEFINITION', re.IGNORECASE), 'SYNOPSIS'), (re.compile('^CONFIG', re.IGNORECASE), 'CONFIGURATION'), (re.compile('^DESCR', re.IGNORECASE), 'DESCRIPTION'), (re.compile('^OPTION', re.IGNORECASE), 'OPTIONS'), (re.compile('^EXIT', re.IGNORECASE), 'EXIT STATUS'), (re.compile('^RETURN', re.IGNORECASE), 'RETURN VALUE'), (re.compile('^ERROR', re.IGNORECASE), 'ERRORS'), (re.compile('^ENVIRON', re.IGNORECASE), 'ENVIRONMENT'), (re.compile('^FILE', re.IGNORECASE), 'FILES'), (re.compile('^VER', re.IGNORECASE), 'VERSIONS'), (re.compile('^ATTR', re.IGNORECASE), 'ATTRIBUTES'), (re.compile('^CONFOR', re.IGNORECASE), 'CONFORMING TO'), (re.compile('^NOTE', re.IGNORECASE), 'NOTES'), (re.compile('^BUG', re.IGNORECASE), 'BUGS'), (re.compile('^EXAMPLE', re.IGNORECASE), 'EXAMPLE'), (re.compile('^SEE', re.IGNORECASE), 'SEE ALSO')]

classmethod sec2man_get_first_child(subtree, *classes)

strip_man_info()

class linuxdoc.manKernelDoc.kernel_doc_man(rawsource='', *children, **attributes)

Bases: Invisible, Element

Node to mark a section as manpage

linuxdoc.manKernelDoc.setup(app)

linuxdoc.manKernelDoc.skip_kernel_doc_man(self, node)