GenIndexDirective
extends BaseDirective
in package
Renders a genindex term listing wherever it's placed, optionally scoped to documents under one or more path prefixes -- unlike the project-wide `:template: genindex` page, this can be dropped inline anywhere and used more than once, e.g. one per version directory in a changelog:
.. genindex::
.. genindex::
:scope: Changelog/12.4/
.. genindex::
:scope: Changelog/12.4/, Changelog/12.4-security/
The A-Z letter index (jumpbox + one heading per letter) can be turned off for small, e.g. per-version, listings where it adds more noise than it saves navigation -- terms are then listed flat, in one table:
.. genindex::
:scope: Changelog/12.4/
:no-letter-index:
The node is populated later by IndexCollectorPass, once entries from every document have been collected; at parse time it's an empty placeholder.
Attributes
- #[Directive]
- $name: 'genindex'
- #[Option]
- $name: 'scope'
- $default: ''
- $description: 'Comma-separated document path prefixes the listing is limited to. Lists the whole project when left out.'
- $example: 'Changelog/12.4/, Changelog/12.4-security/'
- #[Option]
- $name: 'no-letter-index'
- $type: \phpDocumentor\Guides\RestructuredText\Directives\OptionType::Boolean
- $default: false
- $description: 'Lists the terms flat in a single table, without the A-Z jumpbox and the heading per letter.'
Table of Contents
Methods
- createNode() : Node
- getAliases() : string[]
- Allow a directive to be registered under multiple names.
- getName() : string
- Get the directive name
- process() : Node|null
- This is the function called by the parser to process the directive, it can be overloaded to do anything with the document, like tweaking nodes or change the parser context
- processNode() : Node
- This can be overloaded to write a directive that just create one node for the document, which is common
- optionsToArray() : array<string, scalar|null>
- readAllOptions() : array<string, scalar|scalar[]|null>
- readOption() : mixed
- Gets an option value from a directive based on attribute configuration.
Methods
createNode()
public
createNode(DirectiveNode $directiveNode, CompilerContextInterface $compilerContext) : Node
Parameters
- $directiveNode : DirectiveNode
- $compilerContext : CompilerContextInterface
Return values
NodegetAliases()
Allow a directive to be registered under multiple names.
public
getAliases() : string[]
Aliases can be used for directives whose name has been deprecated or allows for multiple spellings.
Return values
string[]getName()
Get the directive name
public
getName() : string
Return values
stringprocess()
This is the function called by the parser to process the directive, it can be overloaded to do anything with the document, like tweaking nodes or change the parser context
public
process(BlockContext $blockContext, Directive $directive) : Node|null
The node that directly follows the directive is also passed to it
Parameters
- $blockContext : BlockContext
-
the current document context with the content of the directive
- $directive : Directive
-
parsed directive containing options and variable
Return values
Node|nullprocessNode()
This can be overloaded to write a directive that just create one node for the document, which is common
public
processNode(BlockContext $blockContext, Directive $directive) : Node
The arguments are the same that process
Parameters
- $blockContext : BlockContext
- $directive : Directive
Return values
NodeoptionsToArray()
protected
optionsToArray(DirectiveOption[] $options) : array<string, scalar|null>
Parameters
- $options : DirectiveOption[]
Return values
array<string, scalar|null>readAllOptions()
protected
final readAllOptions(Directive $directive) : array<string, scalar|scalar[]|null>
Parameters
- $directive : Directive
Return values
array<string, scalar|scalar[]|null>readOption()
Gets an option value from a directive based on attribute configuration.
protected
final readOption(Directive $directive, string $optionName) : mixed
Looks up the option in the directive and returns its value converted to the appropriate type based on the Option attribute defined on this directive class. If the option is not present in the directive, returns the default value from the attribute.
Parameters
- $directive : Directive
-
The directive containing the options
- $optionName : string
-
The name of the option to retrieve
Return values
mixed —The option value converted to the appropriate type, or the default value