Update docs for enabling sphinx.ext.autosummary (#2654)

* fix some errors/warnings on docs source * enable sphinx-autosummary for API reference documentation * Update Makefile * update sphinx configuration
openvinotoolkit · Nov 24, 2023 · aa8d175 · aa8d175
1 parent 89d3c9d
commit aa8d175
Show file tree

Hide file tree

Showing 95 changed files with 120 additions and 1,128 deletions.
diff --git a/.gitignore b/.gitignore
@@ -18,6 +18,7 @@ results/
 build/
 dist/
 !src/otx/recipes/**
+src/otx/recipes/**/__pycache__
 *egg-info
 
 *.pth
@@ -45,3 +46,6 @@ src/**/*.so
 
 # Dataset made by unit-test
 tests/**/detcon_mask/*
+
+# sphinx-autosummary generated files
+docs/**/_autosummary/
diff --git a/docs/Makefile b/docs/Makefile
@@ -23,3 +23,9 @@ html:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Custom clean target that also removes autosummary generated files. Can
+# be removed when https://github.com/sphinx-doc/sphinx/issues/1999 is fixed.
+clean:
+	rm -rf "$(SOURCEDIR)/guide/reference/_autosummary"
+	$(SPHINXBUILD)  -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,8 +33,23 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.napoleon",  # Support for NumPy and Google style docstrings
     'sphinx.ext.autodoc',
     'sphinx_copybutton',
+    "sphinx.ext.autosummary",  # Create neat summary tables
+    "sphinx.ext.viewcode",  # Find the source files
+    "sphinx.ext.autosectionlabel",  # Refer sections its title
+    "sphinx.ext.intersphinx",  # Generate links to the documentation
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+     ".md": "markdown",
+}
+
+suppress_warnings = [
+    "ref.python",
+    "autosectionlabel.*",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -45,7 +60,6 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
-
 # -- Options for HTML output ------------------------------------------------- #
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -74,3 +88,25 @@
 html_css_files = [
     'css/custom.css',
 ]
+
+# -- Extension configuration -------------------------------------------------
+autodoc_docstring_signature = True
+autodoc_member_order = "bysource"
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+autodoc_member_order = "groupwise"
+autodoc_default_options = {
+    "members": True,
+    "methods": True,
+    "special-members": "__call__",
+    "exclude-members": "_abc_impl",
+    "show-inheritance": True,
+}
+
+autoclass_content = "both"
+
+autosummary_generate = True     # Turn on sphinx.ext.autosummary
+autosummary_ignore_module_all = False   # Summary list in __all__ no others
+# autosummary_imported_members = True # document classes and functions imported in modules
diff --git a/docs/source/guide/explanation/algorithms/action/action_classification.rst b/docs/source/guide/explanation/algorithms/action/action_classification.rst
@@ -1,5 +1,5 @@
 Action Classification
-==================
+=====================
 
 Action classification is a problem of identifying the action that is being performed in a video. The input to the algorithm is a sequence of video frames, and the output is a label indicating the action that is being performed.
 

diff --git a/docs/source/guide/explanation/algorithms/anomaly/index.rst b/docs/source/guide/explanation/algorithms/anomaly/index.rst
@@ -143,7 +143,7 @@ Since STFPM trains the student network, we use the following parameters for its
 - ``Aditional Techniques``:
    - ``Early Stopping``: Early stopping is used to stop the training process when the validation loss stops improving. The default value of the early stopping patience is ``10``.
 
-For more information on STFPM's training. We invite you to read Anomalib's `STFPM documentation<https://openvinotoolkit.github.io/anomalib/reference_guide/algorithms/stfpm.html>`_.
+For more information on STFPM's training. We invite you to read Anomalib's `STFPM documentation <https://anomalib.readthedocs.io/en/latest/reference_guide/algorithms/stfpm.htm>`_.
 
 Reconstruction-based Models
 ---------------------------

diff --git a/...urce/guide/explanation/algorithms/classification/multi_class_classification.rst b/...urce/guide/explanation/algorithms/classification/multi_class_classification.rst
@@ -100,7 +100,7 @@ In the table below the top-1 accuracy on some academic datasets using our :ref:`
 +-----------------------+-----------------+-----------+-----------+-----------+
 | EfficientNet-V2-S     | 96.13           | 90.36     | 97.68     | 86.74     |
 +-----------------------+-----------------+-----------+-----------+-----------+
-*These datasets were splitted with auto-split (80% train, 20% test).
+\* These datasets were splitted with auto-split (80% train, 20% test).
 
 ************************
 Semi-supervised Learning
@@ -145,7 +145,6 @@ In the table below the top-1 accuracy on some academic datasets using our pipeli
 |  EfficientNet-V2-S    |  36.03  |  39.66  | 16.81 |  20.28  | 65.99  |  69.61  |
 +-----------------------+---------+---------+-------+---------+--------+---------+
 
-|
 
 - 10 labeled images per class including unlabeled dataset for Semi-SL
 

diff --git a/...urce/guide/explanation/algorithms/classification/multi_label_classification.rst b/...urce/guide/explanation/algorithms/classification/multi_label_classification.rst
@@ -28,6 +28,7 @@ Specifically, this format should be converted in our `internal representation <h
 To convert the COCO data format to our internal one, run this script in similar way:
 
 .. code-block::
+
     python convert_coco_to_multilabel.py --ann_file_path <path to .json COCO annotations> --data_root_dir <path to images folder> --output <output path to save annotations>
 
 .. note::

diff --git a/docs/source/guide/explanation/algorithms/index.rst b/docs/source/guide/explanation/algorithms/index.rst
@@ -11,7 +11,9 @@ To this end, we support:
 - **Supervised training**. This is the most common approach for computer vision tasks such as object detection and image classification. Supervised learning involves training a model on a labeled dataset of images. The model learns to associate specific features in the images with the corresponding labels.
 
 - **Incremental learning**. This learning approach lets the model train on new data as it becomes available, rather than retraining the entire model on the whole dataset every time new data is added. OpenVINO™ Training Extensions supports also the class incremental approach for all tasks. In this approach, the model is first trained on a set of classes, and then incrementally updated with new classes of data, while keeping the previously learned classes' knowledge. The class incremental approach is particularly useful in situations where the number of classes is not fixed and new classes may be added over time.
+
 .. _semi_sl_explanation:
+
 - **Semi-supervised learning**.  This is a type of machine learning in which the model is trained on a dataset that contains a combination of labeled and unlabeled examples. The labeled examples are used to train the model, while the unlabeled examples are used to improve the model's performance by providing additional information about the underlying distribution of the data. This approach is often used when there is a limited amount of labeled data available, but a large amount of unlabeled data. This can make it more cost-effective and efficient to train models compared to traditional supervised learning, where the model is trained only on labeled data.
 
 - **Self-supervised learning**. This is a type of machine learning where the model is trained on a dataset that contains only unlabeled examples. The model is trained to learn useful representations of the data by solving a task that can be inferred from the input itself, without human-provided labels. The objective is to learn good representations of the input data that can then be used for downstream tasks such as classification, detection, generation or clustering.

diff --git a/docs/source/guide/explanation/algorithms/object_detection/object_detection.rst b/docs/source/guide/explanation/algorithms/object_detection/object_detection.rst
@@ -92,6 +92,7 @@ We support the following ready-to-use model templates:
 Above table can be found using the following command
 
 .. code-block::
+
     $ otx find --task detection
 
 `MobileNetV2-ATSS <https://arxiv.org/abs/1912.02424>`_ is a good medium-range model that works well and fast in most cases.
@@ -147,6 +148,7 @@ Please, refer to the :doc:`tutorial <../../../tutorials/advanced/backbones>` how
 To see which public backbones are available for the task, the following command can be executed:
 
 .. code-block::
+
     $ otx find --backbone {torchvision, pytorchcv, mmcls, omz.mmcls}
 
 In the table below the test mAP on some academic datasets using our :ref:`supervised pipeline <od_supervised_pipeline>` is presented.

diff --git a/docs/source/guide/explanation/algorithms/segmentation/instance_segmentation.rst b/docs/source/guide/explanation/algorithms/segmentation/instance_segmentation.rst
@@ -61,11 +61,11 @@ We support the following ready-to-use model templates:
 +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------+---------------------+-----------------+
 | Template ID                                                                                                                                                                                                                                | Name                       | Complexity (GFLOPs) | Model size (MB) |
 +============================================================================================================================================================================================================================================+============================+=====================+=================+
-| `Custom_Counting_Instance_Segmentation_MaskRCNN_EfficientNetB2B <https://github.com/openvinotoolkit/training_extensions/blob/develop/src/otx/algorithms/detection/configs/instance_segmentation/efficientnetb2b_maskrcnn/template.yaml>`_      | MaskRCNN-EfficientNetB2B   | 68.48           | 13.27           |
+| `Custom_Counting_Instance_Segmentation_MaskRCNN_EfficientNetB2B <https://github.com/openvinotoolkit/training_extensions/blob/develop/src/otx/algorithms/detection/configs/instance_segmentation/efficientnetb2b_maskrcnn/template.yaml>`_  | MaskRCNN-EfficientNetB2B   | 68.48               | 13.27           |
 +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------+---------------------+-----------------+
-| `Custom_Counting_Instance_Segmentation_MaskRCNN_ResNet50 <https://github.com/openvinotoolkit/training_extensions/blob/develop/src/otx/algorithms/detection/configs/instance_segmentation/resnet50_maskrcnn/template.yaml>`_                    | MaskRCNN-ResNet50          | 533.80          | 177.90          |
+| `Custom_Counting_Instance_Segmentation_MaskRCNN_ResNet50 <https://github.com/openvinotoolkit/training_extensions/blob/develop/src/otx/algorithms/detection/configs/instance_segmentation/resnet50_maskrcnn/template.yaml>`_                | MaskRCNN-ResNet50          | 533.80              | 177.90          |
 +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------+---------------------+-----------------+
-| `Custom_Counting_Instance_Segmentation_MaskRCNN_ConvNeXt <https://github.com/openvinotoolkit/training_extensions/blob/develop/src/otx/algorithms/detection/configs/instance_segmentation/convnext_maskrcnn/template.yaml>`_                    | MaskRCNN-ConvNeXt          | 266.78          | 192.4          |
+| `Custom_Counting_Instance_Segmentation_MaskRCNN_ConvNeXt <https://github.com/openvinotoolkit/training_extensions/blob/develop/src/otx/algorithms/detection/configs/instance_segmentation/convnext_maskrcnn/template.yaml>`_                | MaskRCNN-ConvNeXt          | 266.78              | 192.4           |
 +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------+---------------------+-----------------+
 
 MaskRCNN-ResNet50 utilizes the `ResNet-50 <https://arxiv.org/abs/1512.03385>`_ architecture as the backbone network for extracting image features. This choice of backbone network results in a higher number of parameters and FLOPs, which consequently requires more training time. However, the model offers superior performance in terms of accuracy.

diff --git a/docs/source/guide/get_started/installation.rst b/docs/source/guide/get_started/installation.rst
@@ -1,5 +1,5 @@
 Installation
-=============
+============
 
 **************
 Prerequisites
@@ -88,9 +88,9 @@ Install ``tox`` and create a development environment:
 
 Then you may change code, and all fixes will be directly applied to the editable package.
 
-****************************************************
+*****************************************************
 Install OpenVINO™ Training Extensions by using Docker
-****************************************************
+*****************************************************
 
 .. code-block::
 

diff --git a/docs/source/guide/get_started/introduction.rst b/docs/source/guide/get_started/introduction.rst
@@ -42,9 +42,9 @@ OpenVINO™ Training Extensions will provide the :doc:`following features <../ex
 - OpenVINO™ Training Extensions uses `Datumaro <https://openvinotoolkit.github.io/datumaro/stable/index.html>`_ as the backend to handle datasets. On account of that, OpenVINO™ Training Extensions supports the most common academic field dataset formats for each task. In the future there will be more supported formats available to give more freedom of datasets format choice.
 - Improved :doc:`auto-configuration functionality <../explanation/additional_features/auto_configuration>`. OpenVINO™ Training Extensions analyzes provided dataset and selects the proper task and model template to provide the best accuracy/speed trade-off. It will also make a random auto-split of your dataset if there is no validation set provided.
 
-************
+*********************
 Documentation content
-************
+*********************
 
 1. **Quick start guide**:
 

diff --git a/docs/source/guide/index.rst b/docs/source/guide/index.rst
@@ -32,11 +32,7 @@ Guide
   :hidden:
   :caption: Reference
 
-  reference/api/index
-  reference/algorithm/index
-  reference/core/index
-  reference/hpo/hpo
-  reference/mpa/index
+  reference/index
 
 
 .. toctree::

diff --git a/docs/source/guide/reference/algorithm/action/adapters/index.rst b/docs/source/guide/reference/algorithm/action/adapters/index.rst
diff --git a/docs/source/guide/reference/algorithm/action/adapters/mmaction.rst b/docs/source/guide/reference/algorithm/action/adapters/mmaction.rst
diff --git a/docs/source/guide/reference/algorithm/action/adapters/openvino.rst b/docs/source/guide/reference/algorithm/action/adapters/openvino.rst
diff --git a/docs/source/guide/reference/algorithm/action/configs.rst b/docs/source/guide/reference/algorithm/action/configs.rst
diff --git a/docs/source/guide/reference/algorithm/action/index.rst b/docs/source/guide/reference/algorithm/action/index.rst
diff --git a/docs/source/guide/reference/algorithm/action/tasks.rst b/docs/source/guide/reference/algorithm/action/tasks.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/adapters/callbacks.rst b/docs/source/guide/reference/algorithm/anomaly/adapters/callbacks.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/adapters/config.rst b/docs/source/guide/reference/algorithm/anomaly/adapters/config.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/adapters/data.rst b/docs/source/guide/reference/algorithm/anomaly/adapters/data.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/adapters/exportable_code.rst b/docs/source/guide/reference/algorithm/anomaly/adapters/exportable_code.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/adapters/index.rst b/docs/source/guide/reference/algorithm/anomaly/adapters/index.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/adapters/logger.rst b/docs/source/guide/reference/algorithm/anomaly/adapters/logger.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/configs.rst b/docs/source/guide/reference/algorithm/anomaly/configs.rst
diff --git a/docs/source/guide/reference/algorithm/anomaly/index.rst b/docs/source/guide/reference/algorithm/anomaly/index.rst