A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier :::). This will override the default heading generated by the plugin. See also the toc_label option.
Not advised to be used as a global configuration option.
This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.
in docs/some_page.md (local configuration)
::: path.to.module
options:
heading: "My fancy module"
When injecting documentation for an object, the object itself and its members are rendered. For each layer of objects, we increase the heading level by 1.
The initial heading level will be used for the first layer. If you set it to 3, then headings will start with <h3>.
Whether to render headings for function/method parameters.
With this option enabled, each function/method parameter (including parameters of __init__ methods merged in their parent class with the merge_init_into_class option) gets a permalink, an entry in the Table of Contents, and an entry in the generated objects inventory. The permalink and inventory entry allow cross-references from internal and external pages.
The identifier used in the permalink and inventory is of the following form: path.to.function(param_name). To manually cross-reference a parameter, you can therefore use this Markdown syntax:
Enabling this option along with signature_crossrefs will automatically render cross-references to parameters in class/function/method signatures and attributes values.
Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after :::).
It is pretty common to inject documentation for one module per page, especially when following our automatic reference pages recipe. Since each page already has a title, usually being the module's name, we can spare one heading level by not showing the heading for the module itself (heading levels are limited to 6 by the HTML specification).
Sparing that extra level can be helpful when your objects tree is deeply nested (e.g. method in a class in a class in a module). If your objects tree is not deeply nested, and you are injecting documentation for many different objects on a single page, it might be preferable to render the heading of each object.
If the root heading is not shown, at least add a ToC entry for it.
If you inject documentation for an object in the middle of a page, after long paragraphs, and without showing the root heading, then you will not be able to link to this particular object as it won't have a permalink and will be "lost" in the middle of text. In that case, it is useful to add a hidden anchor to the document, which will also appear in the table of contents.
In other cases, you might want to disable the entry to avoid polluting the ToC. It is not possible to show the root heading and hide the ToC entry.
Show the full Python path for the root object heading.
The path of a Python object is the dot-separated list of names under which it is accessible, for example package.module.Class.method.
With this option you can choose to show the full path of the object you inject documentation for, or just its name. This option impacts only the object you specify, not its members. For members, see the two other options show_root_members_full_path and show_object_full_path.
When grouped by categories, show a heading for each category. These category headings will appear in the table of contents, allowing you to link to them using their permalinks.
Not recommended with deeply nested objects.
When injecting documentation for deeply nested objects, you'll quickly run out of heading levels, and the objects at the bottom of the tree risk all getting documented using H6 headings, which might decrease the readability of your API docs.
A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier :::). This will override the default label generated by the plugin. See also the heading option.
Not advised to be used as a global configuration option.
This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object.
Use with/without heading.
If you use this option without specifying a custom heading, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for heading and toc_label, we leave the customization entirely up to you.
in docs/some_page.md (local configuration)
::: path.to.module
options:
heading: "My fancy module"
toc_label: "My fancy module"