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 = 'man'

The builder’s output format, or ‘’ if no document output is produced.

get_partial_document(children)

init()

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

is_manpage(node)

name = 'kernel-doc-man'

The builder’s name, for the -b command line option.

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_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)