Directives

Hawkmoth provides several new directives for incorporating documentation comments from C/C++ source files into the reStructuredText document. There are three main types of directives, for incorporating documentation from entire files, for single objects, and for composite objects optionally with members.

Source Files

The c:autodoc and cpp:autodoc directives simply include all the documentation comments from any number of files. This is the most basic and quickest way to generate documentation, but offers no control over what gets included.

.. c:autodoc:: filename-pattern [...]

.. cpp:autodoc:: filename-pattern [...]

Incorporate documentation comments from the files specified by the space separated list of filename patterns given as arguments. The patterns are interpreted relative to the hawkmoth_root configuration option.

:transform: (text)

Override hawkmoth_transform_default for the transform parameter value of the hawkmoth-process-docstring event.

See also hawkmoth.ext.transformations.

:clang: (text)

The clang option extends the hawkmoth_clang configuration option.

For example:

.. c:autodoc:: interface.h

.. c:autodoc:: api/*.[ch] interface.h
   :clang: -DHAWKMOTH

Variables, Types, Macros, and Functions

The c:autovar, c:autotype, c:automacro, and c:autofunction directives and their C++ domain counterparts incorporate the documentation comment for the specified object in the specified file.

The directives support all the same directive options as c:autodoc and cpp:autodoc, adding the file option.

.. c:autovar:: name

.. cpp:autovar:: name

Incorporate the documentation comment for the variable name.

If file is specified, look up name there, otherwise look up name in all previously parsed files in the current document.

:file: (text)

The file option specifies the file to look up name in. This is required if the file has not been parsed yet, and to disambiguate if name is found in multiple files.

The filename is interpreted relative to the hawkmoth_root configuration option.

For example:

.. c:autovar:: example_variable
   :file: example_file.c

.. c:autovar:: another_variable

.. c:autotype:: name

.. cpp:autotype:: name

Same as c:autovar but for typedefs.

.. c:autotype:: example_type_t
   :file: example_file.c

.. c:automacro:: name

.. cpp:automacro:: name

Same as c:autovar but for macros, including function-like macros.

Note

The C++ Domain does not have a cpp:macro directive, so all macros are always in the C Domain. This affects cross-referencing them; see Cross-Referencing C and C++ Constructs for details.

.. c:automacro:: EXAMPLE_MACRO
   :file: example_file.c

.. c:autofunction:: name

.. cpp:autofunction:: name

Same as c:autovar but for functions. (Use c:automacro for function-like macros.)

.. c:autofunction:: example_function
   :file: example_file.c

Structures, Classes, Unions, and Enumerations

The c:autostruct, c:autounion, and c:autoenum directives, their C++ domain counterparts, and the cpp:autoclass directive incorporate the documentation comments for the specified object in the specified file, with additional control over the structure, class or union members and enumeration constants to include.

The directives support all the same directive options as c:autodoc, c:autovar, c:autotype, c:automacro, and c:autofunction, adding the members option.

.. c:autostruct:: name

.. cpp:autostruct:: name

Incorporate the documentation comment for the structure name, optionally including member documentation as specified by members.

The file option is as in c:autovar. If file is specified, look up name there, otherwise look up name in all previously parsed files in the current document.

:members: (text)

The members option specifies the struct members to include:

• If members is not present, do not include member documentation at all.

• If members is specified without arguments, include all member documentation recursively.

• If members is specified with a comma-separated list of arguments, include all specified member documentation recursively.

For example:

.. c:autostruct:: example_struct
   :file: example_file.c

.. c:autostruct:: example_struct
   :members:

.. c:autostruct:: example_struct
   :members: member_one, member_two

.. cpp:autoclass:: name

Same as cpp:autostruct but for classes.

For example:

.. cpp:autoclass:: example_class
   :file: example_file.cpp
   :members: member_one, member_two

.. c:autounion:: name

.. cpp:autounion:: name

Same as c:autostruct but for unions.

.. c:autounion:: example_union
   :file: example_file.c
   :members: some_member

.. c:autoenum:: name

.. cpp:autoenum:: name

Same as c:autostruct but for enums. The enumeration constants are considered members and are included according to the members option.

.. c:autoenum:: example_enum
   :file: example_file.c
   :members:

.. c:autoenum:: example_enum
   :members: CONSTANT_ONE, CONSTANT_TWO

Generic Documentation Sections

The c:autosection and cpp:autosection directives incorporate generic documentation comments not attached to any objects in the specified file.

.. c:autosection:: name

.. cpp:autosection:: name

Incorporate the generic documentation comment identified by name.

The name is derived from the first sentence of the comment, and may contain whitespace. It starts from the first alphanumeric character, inclusive, and extends to the next :, ., or newline, non-inclusive.

The file option is as in c:autovar. If file is specified, look up name there, otherwise look up name in all previously parsed files in the current document.

For example:

/**
 * This is the reference. This is not. It all becomes
 * the documentation comment.
 */

.. c:autosection:: This is the reference
   :file: example_file.c

Note that the above does not automatically create hyperlink targets that you could reference from reStructuredText. However, reStructuredText hyperlink targets work nicely as the reference name for the directive:

/**
 * .. _This is the reference:
 *
 * The actual documentation comment.
 *
 * You can use :ref:`This is the reference` to reference
 * this comment in reStructuredText.
 */

.. c:autosection:: This is the reference
   :file: example_file.c