xcookie.rc.conf_ext module

class xcookie.rc.conf_ext.PatchedPythonDomain(env: BuildEnvironment)

Bases: PythonDomain

References

https://github.com/sphinx-doc/sphinx/issues/3866

resolve_xref(env, fromdocname, builder, typ, target, node, contnode)

Helps to resolves cross-references

class xcookie.rc.conf_ext.GoogleStyleDocstringProcessor(autobuild=1)

Bases: object

A small extension that runs after napoleon and reformats erotemic-flavored google-style docstrings for sphinx.

register_section(tag, alias=None)

Decorator that adds a custom processing function for a non-standard google style tag. The decorated function should accept a list of docstring lines, where the first one will be the google-style tag that likely needs to be replaced, and then return the appropriate sphinx format (TODO what is the name? Is it just RST?).

_register_builtins()

Adds definitions I like of CommandLine, TextArt, and Ignore

process(lines)

Example

>>> import ubelt as ub
>>> self = GoogleStyleDocstringProcessor()
>>> lines = ['Hello world',
>>>              '',
>>>              'CommandLine:',
>>>              '    hi',
>>>              '',
>>>              'CommandLine:',
>>>              '',
>>>              '    bye',
>>>              '',
>>>              'TextArt:',
>>>              '',
>>>              '    1',
>>>              '    2',
>>>              '',
>>>              '    345',
>>>              '',
>>>              'Foobar:',
>>>              '',
>>>              'TextArt:']
>>> new_lines = self.process(lines[:])
>>> print(chr(10).join(new_lines))

process_docstring_callback(app, what_: str, name: str, obj: Any, options: Any, lines: List[str]) → None

Callback to be registered to autodoc-process-docstring

Custom process to transform docstring lines Remove “Ignore” blocks

Parameters:

• app (sphinx.application.Sphinx) – the Sphinx application object

• what (str) – the type of the object which the docstring belongs to (one of “module”, “class”, “exception”, “function”, “method”, “attribute”)

• name (str) – the fully qualified name of the object

• obj – the object itself

• options – the options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are true if the flag option of same name was given to the auto directive

• lines (List[str]) – the lines of the docstring, see above

References

https://www.sphinx-doc.org/en/1.5.1/_modules/sphinx/ext/autodoc.html https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

class xcookie.rc.conf_ext.SphinxDocstring(lines)

Bases: object

Helper to parse and modify sphinx docstrings

find_tagged_lines(tag)

xcookie.rc.conf_ext.paragraph(text)

Wraps multi-line strings and restructures the text to remove all newlines, heading, trailing, and double spaces.

Useful for writing log messages

Parameters:

text (str) – typically a multiline string

Returns:

the reduced text block

Return type:

str

xcookie.rc.conf_ext.create_doctest_figure(app, obj, name, lines)

The idea is that each doctest that produces a figure should generate that and then that figure should be part of the docs.

xcookie.rc.conf_ext.postprocess_hyperlinks(app, doctree, docname)

Extension to fixup hyperlinks. This should be connected to the Sphinx application’s “autodoc-process-docstring” event.

xcookie.rc.conf_ext.fix_rst_todo_section(lines)

xcookie.rc.conf_ext.setup(app)