Cleanup structure of option documentation

docs/_ext/autodoc_analysis.py

@@ -17,6 +17,8 @@
 from typing import Any
 
 from docs._ext.custom_styles.styles import AnalysisDocstring
+from docs._ext.custom_styles.option_parser import process_default_options
+from qiskit.exceptions import QiskitError
 from qiskit_experiments.framework.base_analysis import BaseAnalysis
 from sphinx.application import Sphinx
 from sphinx.ext.autodoc import ClassDocumenter
@@ -38,18 +40,41 @@ 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]
+        try:
+            if self.get_doc() is not None:
+                class_doc, init_doc = self.get_doc()
+            else:
+                return
+        except ValueError:
+            raise QiskitError(
+                f"Documentation of {self.fullname} doesn't match with the expected format."
+                "Please run sphinx build without using the experiment template."
+            )
+
+        option_doc = process_default_options(
+            current_class=self.object,
+            default_option_method="_default_options",
+            section_repr="Analysis Options:",
+            app=self.env.app,
+            options=self.options,
+            config=self.env.app.config,
+            indent=self.content_indent,
+        )
+        init_doc = list(self.process_doc([init_doc]))
 
         # 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,
+            analysis_opts=option_doc,
+            init=init_doc,
         )
 
         # write introduction
-        for i, line in enumerate(self.process_doc(class_doc_parser.generate_class_docs())):
+        custom_docs = class_doc_parser.generate_class_docs()
+        for i, line in enumerate(self.process_doc(custom_docs)):
             self.add_line(line, sourcename, i)
         self.add_line("", sourcename)
 

docs/_ext/autodoc_experiment.py

@@ -17,6 +17,7 @@
 from typing import Any
 
 from docs._ext.custom_styles.styles import ExperimentDocstring
+from docs._ext.custom_styles.option_parser import process_default_options
 from qiskit.exceptions import QiskitError
 from qiskit_experiments.framework.base_experiment import BaseExperiment
 from sphinx.application import Sphinx
@@ -45,27 +46,34 @@ def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
                 return
         except ValueError:
             raise QiskitError(
-                f"Documentation of {self.name} doesn't match with the expected format."
+                f"Documentation of {self.fullname} doesn't match with the expected format."
                 "Please run sphinx build without using the experiment template."
             )
 
+        option_doc = process_default_options(
+            current_class=self.object,
+            default_option_method="_default_experiment_options",
+            section_repr="Experiment Options:",
+            app=self.env.app,
+            options=self.options,
+            config=self.env.app.config,
+            indent=self.content_indent,
+        )
+        init_doc = list(self.process_doc([init_doc]))
+
         # 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,
+            experiment_opts=option_doc,
+            init=init_doc,
         )
 
         # 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])):
+        custom_docs = class_doc_parser.generate_class_docs()
+        for i, line in enumerate(self.process_doc(custom_docs)):
             self.add_line(line, sourcename, i)
         self.add_line("", sourcename)
 

docs/_ext/autodoc_visualization.py

@@ -17,6 +17,7 @@
 from typing import Any
 
 from docs._ext.custom_styles.styles import VisualizationDocstring
+from docs._ext.custom_styles.option_parser import process_default_options
 from qiskit.exceptions import QiskitError
 from qiskit_experiments.visualization import BasePlotter, BaseDrawer
 from sphinx.application import Sphinx
@@ -41,23 +42,42 @@ def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
                 "Please run sphinx build without using the visualization template."
             )
 
+        option_doc = process_default_options(
+            current_class=self.object,
+            default_option_method="_default_options",
+            section_repr="Options:",
+            app=self.env.app,
+            options=self.options,
+            config=self.env.app.config,
+            indent=self.content_indent,
+        )
+        init_doc = list(self.process_doc([init_doc]))
+
+        fig_option_doc = process_default_options(
+            current_class=self.object,
+            default_option_method="_default_figure_options",
+            section_repr="Figure Options:",
+            app=self.env.app,
+            options=self.options,
+            config=self.env.app.config,
+            indent=self.content_indent,
+        )
+
         # format visualization class documentation into the visualization style
         class_doc_parser = VisualizationDocstring(
             target_cls=self.object,
             docstring_lines=class_doc,
             config=self.env.app.config,
             indent=self.content_indent,
+            opts=option_doc,
+            figure_opts=fig_option_doc,
+            init=init_doc,
         )
 
         # 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])):
+        init_doc = list(self.process_doc([init_doc]))
+        custom_docs = class_doc_parser.generate_class_docs()
+        for i, line in enumerate(self.process_doc(custom_docs)):
             self.add_line(line, sourcename, i)
         self.add_line("", sourcename)
 

docs/_ext/custom_styles/formatter.py

@@ -14,7 +14,7 @@
 A class that formats documentation sections.
 """
 from typing import List
-from .utils import _check_no_indent
+from .utils import _check_no_indent, _write_options
 
 
 class DocstringSectionFormatter:
@@ -37,7 +37,11 @@ def format_header(self, lines: List[str]) -> List[str]:
     @_check_no_indent
     def format_overview(self, lines: List[str]) -> List[str]:
         """Format overview section."""
-        format_lines = [".. rubric:: Overview", ""]
+        format_lines = [
+            ""
+            ".. rubric:: Overview",
+            "",
+        ]
         format_lines.extend(lines)
         format_lines.append("")
 
@@ -46,7 +50,10 @@ def format_overview(self, lines: List[str]) -> List[str]:
     @_check_no_indent
     def format_reference(self, lines: List[str]) -> List[str]:
         """Format reference section."""
-        format_lines = [".. rubric:: References", ""]
+        format_lines = [
+            ".. rubric:: References",
+            "",
+        ]
         format_lines.extend(lines)
         format_lines.append("")
 
@@ -64,7 +71,10 @@ def format_warning(self, lines: List[str]) -> List[str]:
     @_check_no_indent
     def format_example(self, lines: List[str]) -> List[str]:
         """Format example section."""
-        format_lines = [".. rubric:: Example", ""]
+        format_lines = [
+            ".. rubric:: Example",
+            "",
+        ]
         format_lines.extend(lines)
         format_lines.append("")
 
@@ -82,7 +92,10 @@ def format_note(self, lines: List[str]) -> List[str]:
     @_check_no_indent
     def format_see_also(self, lines: List[str]) -> List[str]:
         """Format see also section."""
-        format_lines = [".. rubric:: See Also", ""]
+        format_lines = [
+            ".. rubric:: See also",
+            "",
+        ]
 
         format_lines.extend(lines)
         format_lines.append("")
@@ -92,32 +105,8 @@ def format_see_also(self, lines: List[str]) -> List[str]:
     @_check_no_indent
     def format_manual(self, lines: List[str]) -> List[str]:
         """Format user manual section."""
-        format_lines = [".. rubric:: User Manual", ""]
-        format_lines.extend(lines)
-        format_lines.append("")
-
-        return format_lines
-
-
-class ExperimentSectionFormatter(DocstringSectionFormatter):
-    """Formatter for experiment class."""
-
-    @_check_no_indent
-    def format_analysis_ref(self, lines: List[str]) -> List[str]:
-        """Format analysis class reference section."""
-        format_lines = [".. rubric:: Analysis Class Reference", ""]
-        format_lines.extend(lines)
-        format_lines.append("")
-
-        return format_lines
-
-    @_check_no_indent
-    def format_experiment_opts(self, lines: List[str]) -> List[str]:
-        """Format experiment options section."""
         format_lines = [
-            ".. rubric:: Experiment Options",
-            "",
-            "These options can be set by the :meth:`set_experiment_options` method.",
+            ".. rubric:: User manual",
             "",
         ]
         format_lines.extend(lines)
@@ -126,26 +115,26 @@ def format_experiment_opts(self, lines: List[str]) -> List[str]:
         return format_lines
 
     @_check_no_indent
-    def format_analysis_opts(self, lines: List[str]) -> List[str]:
-        """Format analysis options section."""
+    def format_init(self, lines: List[str]) -> List[str]:
+        """Format user manual section."""
         format_lines = [
-            ".. rubric:: Analysis Options",
-            "",
-            "These options can be set by the :meth:`analysis.set_options` method.",
+            ".. rubric:: Initialization",
             "",
         ]
         format_lines.extend(lines)
         format_lines.append("")
 
         return format_lines
 
+
+class ExperimentSectionFormatter(DocstringSectionFormatter):
+    """Formatter for experiment class."""
+
     @_check_no_indent
-    def format_transpiler_opts(self, lines: List[str]) -> List[str]:
-        """Format transpiler options section."""
+    def format_analysis_ref(self, lines: List[str]) -> List[str]:
+        """Format analysis class reference section."""
         format_lines = [
-            ".. rubric:: Transpiler Options",
-            "",
-            "This option can be set by the :meth:`set_transpile_options` method.",
+            ".. rubric:: Analysis class reference",
             "",
         ]
         format_lines.extend(lines)
@@ -154,15 +143,16 @@ def format_transpiler_opts(self, lines: List[str]) -> List[str]:
         return format_lines
 
     @_check_no_indent
-    def format_run_opts(self, lines: List[str]) -> List[str]:
-        """Format run options section."""
+    def format_experiment_opts(self, lines: List[str]) -> List[str]:
+        """Format experiment options section."""
         format_lines = [
-            ".. rubric:: Backend Run Options",
+            ".. rubric:: Experiment options",
             "",
-            "This option can be set by the :meth:`set_run_options` method.",
+            "These options can be set by the :meth:`set_experiment_options` method.",
             "",
         ]
-        format_lines.extend(lines)
+        for line in _write_options(lines, self.indent):
+            format_lines.append(line)
         format_lines.append("")
 
         return format_lines
@@ -175,12 +165,13 @@ class AnalysisSectionFormatter(DocstringSectionFormatter):
     def format_analysis_opts(self, lines: List[str]) -> List[str]:
         """Format analysis options section."""
         format_lines = [
-            ".. rubric:: Run Options",
+            ".. rubric:: Analysis options",
             "",
             "These are the keyword arguments of :meth:`run` method.",
             "",
         ]
-        format_lines.extend(lines)
+        for line in _write_options(lines, self.indent):
+            format_lines.append(line)
         format_lines.append("")
 
         return format_lines
@@ -189,7 +180,7 @@ def format_analysis_opts(self, lines: List[str]) -> List[str]:
     def format_fit_model(self, lines: List[str]) -> List[str]:
         """Format fit model section."""
         format_lines = [
-            ".. rubric:: Fit Model",
+            ".. rubric:: Fit model",
             "",
             "This is the curve fitting analysis. ",
             "The following equation(s) are used to represent curve(s).",
@@ -204,7 +195,7 @@ def format_fit_model(self, lines: List[str]) -> List[str]:
     def format_fit_parameters(self, lines: List[str]) -> List[str]:
         """Format fit parameter section."""
         format_lines = [
-            ".. rubric:: Fit Parameters",
+            ".. rubric:: Fit parameters",
             "",
             "The following fit parameters are estimated during the analysis.",
             "",
@@ -228,7 +219,8 @@ def format_opts(self, lines: List[str]) -> List[str]:
             "The following can be set using :meth:`set_options`.",
             "",
         ]
-        format_lines.extend(lines)
+        for line in _write_options(lines, self.indent):
+            format_lines.append(line)
         format_lines.append("")
 
         return format_lines
@@ -237,12 +229,13 @@ def format_opts(self, lines: List[str]) -> List[str]:
     def format_figure_opts(self, lines: List[str]) -> List[str]:
         """Format figure options section."""
         format_lines = [
-            ".. rubric:: Figure Options",
+            ".. rubric:: Figure options",
             "",
             "The following can be set using :meth:`set_figure_options`.",
             "",
         ]
-        format_lines.extend(lines)
+        for line in _write_options(lines, self.indent):
+            format_lines.append(line)
         format_lines.append("")
 
         return format_lines