Guides

IndexDirective extends BaseDirective
in package
uses ReportsViolations

FinalYes

Collects index entries, example:

.. index:: single: installation

.. index:: single: configuration pair: configuration; file see: token; access token ! main entry example

A line may also hold several comma-separated, type-less entries at once, each becoming its own "single" entry -- not specific to any one project, this convention is used for example by TYPO3's Core Changelog files:

.. index:: Backend, PHP-API, NotScanned, ext:core

The directive itself is invisible in the rendered page; entries are collected project-wide to build the genindex page.

A :name: makes the entries a target a :ref: can link to, landing on the section they are filed under:

.. index:: single: installation :name: install-entry

Tags
link
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index
Attributes
#[Directive]
$name: 'index'
$rawContent: true
#[Option]
$name: 'name'
$description: 'Makes the entries a target a :ref: can link to, landing on the section they are filed under.'

Table of Contents

Constants

TYPO_DISTANCE_THRESHOLD  : mixed = 2
A colon-prefixed segment whose prefix is this close (or closer) to a real type name is very likely a typo of it, e.g. "sindle:" -> "single:" (distance 1). Anything further away, e.g. "ext:" in "ext:core", is left alone as an intentional literal colon -- the comma-separated, type-less form (see class docblock) routinely contains those.

Properties

$logger  : LoggerInterface|ViolationReporter

Methods

__construct()  : mixed
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.
parseLine()  : IndexEntryNode
reportViolation()  : void
trimAndFilterEmpty()  : string[]
warnIfLikelyTypo()  : void

Constants

TYPO_DISTANCE_THRESHOLD

A colon-prefixed segment whose prefix is this close (or closer) to a real type name is very likely a typo of it, e.g. "sindle:" -> "single:" (distance 1). Anything further away, e.g. "ext:" in "ext:core", is left alone as an intentional literal colon -- the comma-separated, type-less form (see class docblock) routinely contains those.

private mixed TYPO_DISTANCE_THRESHOLD = 2

Properties

Methods

getAliases()

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
string

process()

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|null

processNode()

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
Node

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

trimAndFilterEmpty()

private trimAndFilterEmpty(string[] $items) : string[]
Parameters
$items : string[]
Return values
string[]

warnIfLikelyTypo()

private warnIfLikelyTypo(string $candidate, string $line, DirectiveNode $directiveNode) : void
Parameters
$candidate : string
$line : string
$directiveNode : DirectiveNode
On this page

Search results