👌 IMPROVE: use autodoc2-docstring directive

README.md

@@ -58,7 +58,7 @@ I've use a lot of their code, for the `astroid` static analysis, but I've made a
 - fixed `a | b` annotations inference
 - added analysis of `functools.singledispatch` and their registers
 - handling of `__all__`
-- the summary only got the first line, not first paragraph
+- docstrings (and summaries) are now parsed with the correct source/line, i.e. warnings point to the correct location in the source file
 - added `:canonical:` to `py` directives
 - Moved away from using jinja templates, to using python functions
   - IMO the templates were too complex and hard to read,

docs/apidocs/aiida/aiida.parsers.rst

@@ -7,7 +7,9 @@
 Description
 -----------
 
-Module for classes and utilities to write parsers for calculation jobs.
+.. autodoc2-docstring:: aiida.parsers
+   :renderer: rst
+   :allowtitles:
 
 Package Contents
 ----------------
@@ -20,7 +22,9 @@ Classes
    :align: left
 
    * - :py:obj:`Parser <aiida.parsers.parser.Parser>`
-     - Base class for a Parser that can parse the outputs produced by a CalcJob process.
+     - .. autodoc2-docstring:: aiida.parsers.parser.Parser
+          :renderer: rst
+          :summary:
 
 API
 ~~~
@@ -30,94 +34,69 @@ API
 
    Bases: :py:obj:`abc.ABC`
 
-   Base class for a Parser that can parse the outputs produced by a CalcJob process.
+   .. autodoc2-docstring:: aiida.parsers.parser.Parser
+      :renderer: rst
 
    .. rubric:: Initialization
 
-   Construct the Parser instance.
-
-   :param node: the `CalcJobNode` that contains the results of the executed `CalcJob` process.
+   .. autodoc2-docstring:: aiida.parsers.parser.Parser.__init__
+      :renderer: rst
 
    .. py:property:: logger
       :canonical: aiida.parsers.parser.Parser.logger
 
-      Return the logger preconfigured for the calculation node associated with this parser instance.
-
-      :return: `logging.Logger`
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.logger
+         :renderer: rst
 
    .. py:property:: node
       :canonical: aiida.parsers.parser.Parser.node
       :type: aiida.orm.CalcJobNode
 
-      Return the node instance
-
-      :return: the `CalcJobNode` instance
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.node
+         :renderer: rst
 
    .. py:property:: exit_codes
       :canonical: aiida.parsers.parser.Parser.exit_codes
       :type: aiida.engine.ExitCodesNamespace
 
-      Return the exit codes defined for the process class of the node being parsed.
-
-      :returns: ExitCodesNamespace of ExitCode named tuples
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.exit_codes
+         :renderer: rst
 
    .. py:property:: retrieved
       :canonical: aiida.parsers.parser.Parser.retrieved
       :type: aiida.orm.FolderData
 
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.retrieved
+         :renderer: rst
+
    .. py:property:: outputs
       :canonical: aiida.parsers.parser.Parser.outputs
 
-      Return the dictionary of outputs that have been registered.
-
-      :return: an AttributeDict instance with the registered output nodes
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.outputs
+         :renderer: rst
 
    .. py:method:: out(link_label: str, node: aiida.orm.Data) -> None
       :canonical: aiida.parsers.parser.Parser.out
 
-      Register a node as an output with the given link label.
-
-      :param link_label: the name of the link label
-      :param node: the node to register as an output
-      :raises aiida.common.ModificationNotAllowed: if an output node was already registered with the same link label
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.out
+         :renderer: rst
 
    .. py:method:: get_outputs_for_parsing()
       :canonical: aiida.parsers.parser.Parser.get_outputs_for_parsing
 
-      Return the dictionary of nodes that should be passed to the `Parser.parse` call.
-
-      Output nodes can be marked as being required by the `parse` method, by setting the `pass_to_parser` attribute,
-      in the `spec.output` call in the process spec of the `CalcJob`, to True.
-
-      :return: dictionary of nodes that are required by the `parse` method
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.get_outputs_for_parsing
+         :renderer: rst
 
    .. py:method:: parse_from_node(node: aiida.orm.CalcJobNode, store_provenance=True, retrieved_temporary_folder=None) -> typing.Tuple[typing.Optional[typing.Dict[str, typing.Any]], aiida.orm.CalcFunctionNode]
       :canonical: aiida.parsers.parser.Parser.parse_from_node
       :classmethod:
 
-      Parse the outputs directly from the `CalcJobNode`.
-
-      If `store_provenance` is set to False, a `CalcFunctionNode` will still be generated, but it will not be stored.
-      It's storing method will also be disabled, making it impossible to store, because storing it afterwards would
-      not have the expected effect, as the outputs it produced will not be stored with it.
-
-      This method is useful to test parsing in unit tests where a `CalcJobNode` can be mocked without actually having
-      to run a `CalcJob`. It can also be useful to actually re-perform the parsing of a completed `CalcJob` with a
-      different parser.
-
-      :param node: a `CalcJobNode` instance
-      :param store_provenance: bool, if True will store the parsing as a `CalcFunctionNode` in the provenance
-      :param retrieved_temporary_folder: absolute path to folder with contents of `retrieved_temporary_list`
-      :return: a tuple of the parsed results and the `CalcFunctionNode` representing the process of parsing
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.parse_from_node
+         :renderer: rst
 
    .. py:method:: parse(**kwargs) -> typing.Optional[aiida.engine.ExitCode]
       :canonical: aiida.parsers.parser.Parser.parse
       :abstractmethod:
 
-      Parse the contents of the output files retrieved in the `FolderData`.
-
-      This method should be implemented in the sub class. Outputs can be registered through the `out` method.
-      After the `parse` call finishes, the runner will automatically link them up to the underlying `CalcJobNode`.
-
-      :param kwargs: output nodes attached to the `CalcJobNode` of the parser instance.
-      :return: an instance of ExitCode or None
+      .. autodoc2-docstring:: aiida.parsers.parser.Parser.parse
+         :renderer: rst