Main directive entry function, called by docutils upon encountering the directive. This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does: * find out if called as a domain-specific directive, set self.do
(self)
| 181 | return '' |
| 182 | |
| 183 | def run(self) -> list[Node]: |
| 184 | """Main directive entry function, called by docutils upon encountering the |
| 185 | directive. |
| 186 | |
| 187 | This directive is meant to be quite easily subclassable, so it delegates |
| 188 | to several additional methods. What it does: |
| 189 | |
| 190 | * find out if called as a domain-specific directive, set self.domain |
| 191 | * create a `desc` node to fit all description inside |
| 192 | * parse standard options, currently `no-index` |
| 193 | * create an index node if needed as self.indexnode |
| 194 | * parse all given signatures (as returned by self.get_signatures()) |
| 195 | using self.handle_signature(), which should either return a name |
| 196 | or raise ValueError |
| 197 | * add index entries using self.add_target_and_index() |
| 198 | * parse the content and handle doc fields in it |
| 199 | """ |
| 200 | if ':' in self.name: |
| 201 | self.domain, _, self.objtype = self.name.partition(':') |
| 202 | else: |
| 203 | self.domain, self.objtype = '', self.name |
| 204 | self.indexnode = addnodes.index(entries=[]) |
| 205 | |
| 206 | node = addnodes.desc() |
| 207 | node.document = self.state.document |
| 208 | source, line = self.get_source_info() |
| 209 | # If any options were specified to the directive, |
| 210 | # self.state.document.current_line will at this point be set to |
| 211 | # None. To ensure nodes created as part of the signature have a line |
| 212 | # number set, set the document's line number correctly. |
| 213 | # |
| 214 | # Note that we need to subtract one from the line number since |
| 215 | # note_source uses 0-based line numbers. |
| 216 | if line is not None: |
| 217 | line -= 1 |
| 218 | self.state.document.note_source(source, line) # type: ignore[arg-type] |
| 219 | node['domain'] = self.domain |
| 220 | # 'desctype' is a backwards compatible attribute |
| 221 | node['objtype'] = node['desctype'] = self.objtype |
| 222 | |
| 223 | # Copy old option names to new ones |
| 224 | # xref RemovedInSphinx90Warning |
| 225 | # deprecate noindex, noindexentry, and nocontentsentry in Sphinx 9.0 |
| 226 | if 'no-index' not in self.options and 'noindex' in self.options: |
| 227 | self.options['no-index'] = self.options['noindex'] |
| 228 | if 'no-index-entry' not in self.options and 'noindexentry' in self.options: |
| 229 | self.options['no-index-entry'] = self.options['noindexentry'] |
| 230 | if ( |
| 231 | 'no-contents-entry' not in self.options |
| 232 | and 'nocontentsentry' in self.options |
| 233 | ): |
| 234 | self.options['no-contents-entry'] = self.options['nocontentsentry'] |
| 235 | |
| 236 | node['no-index'] = node['noindex'] = no_index = 'no-index' in self.options |
| 237 | node['no-index-entry'] = node['noindexentry'] = 'no-index-entry' in self.options |
| 238 | node['no-contents-entry'] = node['nocontentsentry'] = ( |
| 239 | 'no-contents-entry' in self.options |
| 240 | ) |
nothing calls this directly
no test coverage detected