Automatic documentation for experiment and analysis

docs/_ext/autodoc_analysis.py

@@ -0,0 +1,67 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Documentation extension for analysis class.
+"""
+
+from typing import Any
+
+from docs._ext.custom_styles.styles import AnalysisDocstring
+from qiskit_experiments.framework.base_analysis import BaseAnalysis
+from sphinx.application import Sphinx
+from sphinx.ext.autodoc import ClassDocumenter
+
+
+class AnalysisDocumenter(ClassDocumenter):
+    """Sphinx extension for the custom documentation of the standard analysis class."""
+
+    objtype = "analysis"
+    directivetype = 'class'
+    priority = 10 + ClassDocumenter.priority
+    option_spec = dict(ClassDocumenter.option_spec)
+
+    @classmethod
+    def can_document_member(
+        cls, member: Any, membername: str, isattr: bool, parent: Any
+    ) -> bool:
+        return isinstance(member, BaseAnalysis)
+
+    def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
+        sourcename = self.get_sourcename()
+
+        # analysis class doesn't have explicit init method.
+        class_doc = self.get_doc()[0]
+
+        # format experiment documentation into the analysis style
+        class_doc_parser = AnalysisDocstring(
+            target_cls=self.object,
+            docstring_lines=class_doc,
+            config=self.env.app.config,
+            indent=self.content_indent,
+        )
+
+        # write introduction
+        for i, line in enumerate(self.process_doc(class_doc_parser.generate_class_docs())):
+            self.add_line(line, sourcename, i)
+        self.add_line("", sourcename)
+
+        # method and attributes
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
+
+
+def setup(app: Sphinx):
+    existing_documenter = app.registry.documenters.get(AnalysisDocumenter.objtype)
+    if existing_documenter is None or not issubclass(existing_documenter, AnalysisDocumenter):
+        app.add_autodocumenter(AnalysisDocumenter, override=True)

docs/_ext/autodoc_experiment.py

@@ -0,0 +1,80 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Documentation extension for experiment class.
+"""
+
+from typing import Any
+
+from docs._ext.custom_styles.styles import ExperimentDocstring
+from qiskit.exceptions import QiskitError
+from qiskit_experiments.framework.base_experiment import BaseExperiment
+from sphinx.application import Sphinx
+from sphinx.ext.autodoc import ClassDocumenter
+
+
+class ExperimentDocumenter(ClassDocumenter):
+    """Sphinx extension for the custom documentation of the standard experiment class."""
+
+    objtype = "experiment"
+    directivetype = 'class'
+    priority = 10 + ClassDocumenter.priority
+    option_spec = dict(ClassDocumenter.option_spec)
+
+    @classmethod
+    def can_document_member(
+        cls, member: Any, membername: str, isattr: bool, parent: Any
+    ) -> bool:
+        return isinstance(member, BaseExperiment)
+
+    def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
+        sourcename = self.get_sourcename()
+
+        try:
+            class_doc, init_doc = self.get_doc()
+        except ValueError:
+            raise QiskitError(
+                f"Documentation of {self.name} doesn't match with the expected format."
+                "Please run sphinx build without using the experiment template."
+            )
+
+        # format experiment documentation into the experiment style
+        class_doc_parser = ExperimentDocstring(
+            target_cls=self.object,
+            docstring_lines=class_doc,
+            config=self.env.app.config,
+            indent=self.content_indent,
+        )
+
+        # write introduction
+        for i, line in enumerate(self.process_doc(class_doc_parser.generate_class_docs())):
+            self.add_line(line, sourcename, i)
+        self.add_line("", sourcename)
+
+        # write init method documentation
+        self.add_line(".. rubric:: Initialization", sourcename)
+        self.add_line("", sourcename)
+        for i, line in enumerate(self.process_doc([init_doc])):
+            self.add_line(line, sourcename, i)
+        self.add_line("", sourcename)
+
+        # method and attributes
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
+
+
+def setup(app: Sphinx):
+    existing_documenter = app.registry.documenters.get(ExperimentDocumenter.objtype)
+    if existing_documenter is None or not issubclass(existing_documenter, ExperimentDocumenter):
+        app.add_autodocumenter(ExperimentDocumenter, override=True)

docs/_ext/autoref.py

@@ -0,0 +1,105 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Helper directive to generate reference in convenient form.
+"""
+import arxiv
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from sphinx.application import Sphinx
+
+
+class WebSite(Directive):
+    """A custom helper directive for showing website link.
+
+    This can be used, for example,
+
+    .. code-block::
+
+        .. ref_website:: qiskit-experiments, https://github.com/Qiskit/qiskit-experiments
+
+    """
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self):
+        try:
+            name, url = self.arguments[0].split(",")
+        except ValueError:
+            raise ValueError(
+                f"{self.arguments[0]} is invalid website directive format. "
+                "Name and URL should be separated by a single comma."
+            )
+
+        link_name = nodes.paragraph(text=f"{name} ")
+        link_name += nodes.reference(text="(open)", refuri=url)
+
+        return [link_name]
+
+
+class Arxiv(Directive):
+    """A custom helper directive for generating journal information from arXiv id.
+
+    This directive takes two arguments
+
+    - Arbitrary reference name (no white space should be included)
+
+    - arXiv ID
+
+    This can be used, for example,
+
+    .. code-block::
+
+        .. ref_arxiv:: qasm3-paper 2104.14722
+
+    If an article is not found, no journal information will be shown.
+
+    """
+    required_arguments = 2
+    optional_arguments = 0
+    final_argument_whitespace = False
+
+    def run(self):
+
+        # search arXiv database
+        try:
+            search = arxiv.Search(id_list=[self.arguments[1]])
+            paper = next(search.results())
+        except Exception:
+            return []
+
+        # generate journal link nodes
+        ret_node = nodes.paragraph()
+
+        journal = ""
+        if paper.journal_ref:
+            journal += f", {paper.journal_ref}, "
+        if paper.doi:
+            journal += f"doi: {paper.doi}"
+
+        ret_node += nodes.Text(f"[{self.arguments[0]}] ")
+        ret_node += nodes.Text(", ".join([author.name for author in paper.authors]) + ", ")
+        ret_node += nodes.emphasis(text=f"{paper.title}")
+        if journal:
+            ret_node += nodes.Text(journal)
+        ret_node += nodes.Text(" ")
+        ret_node += nodes.reference(text="(open)", refuri=paper.pdf_url)
+
+        return [ret_node]
+
+
+def setup(app: Sphinx):
+    app.add_directive("ref_arxiv", Arxiv)
+    app.add_directive("ref_website", WebSite)

docs/_ext/custom_styles/example/__init__.py

@@ -0,0 +1,48 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+=======================================================================
+Example Documentation (:mod:`qiskit_experiments.documentation.example`)
+=======================================================================
+
+.. currentmodule:: qiskit_experiments.documentation.example
+
+
+.. warning::
+
+    This module is just an example for documentation. Do not import.
+
+.. note::
+
+    Under the autosummary directive you need to set template to trigger custom documentation.
+
+
+Experiments
+===========
+.. autosummary::
+    :toctree: ../stubs/
+    :template: autosummary/experiment.rst
+
+    DocumentedExperiment
+
+Analysis
+========
+.. autosummary::
+    :toctree: ../stubs/
+    :template: autosummary/analysis.rst
+
+    DocumentedCurveAnalysis
+
+"""
+
+from .example_experiment import DocumentedExperiment, DocumentedCurveAnalysis