ase_notebook.attr_doc module

attrs class wrapper to create a docstring from the metadata.

ase_notebook.attr_doc.autodoc(attrs_class)

Decorate an attr.s class to update its docstring with attributes.

The docstring will include the attributes, and emits warnings when partially undocumented attributes are found.

If the class contains any attributes, they are documented as constructor parameters in a Parameters section, added at the end of the class’ docstring. In order to extract the most information per parameter description, this decorator assumes that every attribute

• Typed (either via the type argument, or via PEP 526 type-annotations), and

• Contains a metadata dictionary with the keys

  help:

  The string that describes the attribute, and will go in the description of the corresponding parameter.

Default values are, of course, optional, and if provided, the parameter’s description will inform this. Private attributes will have their names rendered correctly (no leading underscore), and non-private attributes help-text will be complemented with a reminder that the parameter’s value can be later accessed via an attribute with that name.

Warning

Currently, there is no support for indicating that arguments are keyword-only, hashable, or validated. These and other exceptional conditions should be informed in the docstring.

ase_notebook.attr_doc.type_to_sphinx(typ, field_name)

Convert a type object to a string acceptable by Sphinx.