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 thetransform
parameter value of thehawkmoth-process-docstring
event.See also hawkmoth.ext.transformations.
- :clang: (text)¶
The
clang
option extends thehawkmoth_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 upname
there, otherwise look upname
in all previously parsed files in the current document.- :file: (text)¶
The
file
option specifies the file to look upname
in. This is required if the file has not been parsed yet, and to disambiguate ifname
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. (Usec: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 bymembers
.The
file
option is as inc:autovar
. Iffile
is specified, look upname
there, otherwise look upname
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 themembers
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 inc:autovar
. Iffile
is specified, look upname
there, otherwise look upname
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