Updates docs for release (#936)

### Summary * Added docs workflow for stable release * Updated some docstrings * Fixed some docs build errors  ### How to test  ### Checklist  - [ ] I have added unit tests to cover my changes. - [ ] I have added integration tests to cover my changes. - [ ] I have added the description of my changes into [CHANGELOG](https://github.com/openvinotoolkit/datumaro/blob/develop/CHANGELOG.md). - [ ] I have updated the [documentation](https://github.com/openvinotoolkit/datumaro/tree/develop/docs) accordingly ### License - [ ] I submit _my code changes_ under the same [MIT License](https://github.com/openvinotoolkit/datumaro/blob/develop/LICENSE) that covers the project. Feel free to contact the maintainers if that's a concern. - [ ] I have updated the license header for each file (see an example below). ```python # Copyright (C) 2023 Intel Corporation # # SPDX-License-Identifier: MIT ```
openvinotoolkit · Apr 17, 2023 · f640c2c · f640c2c
1 parent a2325b1
commit f640c2c
Show file tree

Hide file tree

Showing 17 changed files with 93 additions and 64 deletions.
diff --git a/.github/workflows/docs_stable.yml b/.github/workflows/docs_stable.yml
@@ -0,0 +1,34 @@
+name: Build Docs for releases
+
+on:
+  workflow_dispatch: # run on request (no need for PR)
+  release:
+    types: [published]
+
+jobs:
+  Build-Docs:
+    runs-on: ubuntu-20.04
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: python -m pip install tox
+      - name: Build-Docs
+        run: |
+          echo RELEASE_VERSION=${GITHUB_REF#refs/*/} >> $GITHUB_ENV
+          tox -e build-doc
+      # - name: Deploy
+      #   uses: peaceiris/actions-gh-pages@v3
+      #   with:
+      #     github_token: ${{ secrets.GITHUB_TOKEN }}
+      #     publish_dir: ./public
+      #     destination_dir: ${{ env.RELEASE_VERSION }}
+      #     force_orphan: true
diff --git a/docs/contributing.md → contributing.md b/docs/contributing.md → contributing.md
diff --git a/datumaro/cli/util/project.py b/datumaro/cli/util/project.py
@@ -153,7 +153,7 @@ def split_local_revpath(revpath: str) -> Tuple[Revision, str]:
 
     A local revpath is a path to a revision withing the current project.
     The syntax is:
-      - [ <revision> : ] [ <target> ]
+        - [ <revision> : ] [ <target> ]
     At least one part must be present.
 
     Returns: (revision, build target)

diff --git a/datumaro/plugins/data_formats/common_semantic_segmentation.py b/datumaro/plugins/data_formats/common_semantic_segmentation.py
@@ -165,19 +165,19 @@ def find_sources(cls, path):
 class CommonSemanticSegmentationWithSubsetDirsImporter(CommonSemanticSegmentationImporter):
     """It supports the following subset sub-directory structure for CommonSemanticSegmentation.
 
-    ```
-    Dataset/
-    └─ <split: train,val, ...>
-        ├── dataset_meta.json # a list of labels
-        ├── images/
-        │   ├── <img1>.png
-        │   ├── <img2>.png
-        │   └── ...
-        └── masks/
-            ├── <img1>.png
-            ├── <img2>.png
-            └── ...
+    .. code-block::
+
+        Dataset/
+        └─ <split: train,val, ...>
+            ├── dataset_meta.json # a list of labels
+            ├── images/
+            │   ├── <img1>.png
+            │   ├── <img2>.png
+            │   └── ...
+            └── masks/
+                ├── <img1>.png
+                ├── <img2>.png
+                └── ...
 
     Then, the imported dataset will have train, val, ... CommonSemanticSegmentation subsets.
-    ```
     """
diff --git a/datumaro/plugins/data_formats/datumaro_binary/mapper/__init__.py b/datumaro/plugins/data_formats/datumaro_binary/mapper/__init__.py
@@ -5,7 +5,7 @@
 # ruff: noqa: F405
 
 from .annotation import *
-from .common import *
+from .common import DictMapper, FloatListMapper, IntListMapper, Mapper, StringMapper
 from .dataset_item import *
 from .media import *
 

diff --git a/datumaro/plugins/data_formats/imagenet.py b/datumaro/plugins/data_formats/imagenet.py
@@ -66,12 +66,15 @@ class ImagenetImporter(Importer):
     """TorchVision's ImageFolder style importer.
     For example, it imports the following directory structure.
 
-    root
-    ├── label_0
-    │   ├── label_0_1.jpg
-    │   └── label_0_2.jpg
-    └── label_1
-        └── label_1_1.jpg
+    .. code-block:: text
+
+        root
+        ├── label_0
+        │   ├── label_0_1.jpg
+        │   └── label_0_2.jpg
+        └── label_1
+            └── label_1_1.jpg
+
     """
 
     @classmethod
@@ -106,25 +109,27 @@ class ImagenetWithSubsetDirsImporter(ImagenetImporter):
     """TorchVision ImageFolder style importer.
     For example, it imports the following directory structure.
 
-    root
-    ├── train
-    │   ├── label_0
-    │   │   ├── label_0_1.jpg
-    │   │   └── label_0_2.jpg
-    │   └── label_1
-    │       └── label_1_1.jpg
-    ├── val
-    │   ├── label_0
-    │   │   ├── label_0_1.jpg
-    │   │   └── label_0_2.jpg
-    │   └── label_1
-    │       └── label_1_1.jpg
-    └── test
-        ├── label_0
-        │   ├── label_0_1.jpg
-        │   └── label_0_2.jpg
-        └── label_1
-            └── label_1_1.jpg
+    .. code-block::
+
+        root
+        ├── train
+        │   ├── label_0
+        │   │   ├── label_0_1.jpg
+        │   │   └── label_0_2.jpg
+        │   └── label_1
+        │       └── label_1_1.jpg
+        ├── val
+        │   ├── label_0
+        │   │   ├── label_0_1.jpg
+        │   │   └── label_0_2.jpg
+        │   └── label_1
+        │       └── label_1_1.jpg
+        └── test
+            ├── label_0
+            │   ├── label_0_1.jpg
+            │   └── label_0_2.jpg
+            └── label_1
+                └── label_1_1.jpg
 
     Then, it will have three subsets: train, val, and test and they have label_0 and label_1 labels.
     """

diff --git a/datumaro/plugins/sampler/random_sampler.py b/datumaro/plugins/sampler/random_sampler.py
@@ -15,7 +15,7 @@
 
 
 class RandomSampler(Transform, CliPlugin):
-    """
+    r"""
     Sampler that keeps no more than required number of items in the dataset.|n
     |n
     Notes:|n

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -63,7 +63,8 @@
 
 suppress_warnings = [
     # "myst.xref_missing",
-    "myst.iref_ambiguous"
+    "myst.iref_ambiguous",
+    "autosectionlabel.*",
 ]
 
 autosummary_generate = True  # Turn on sphinx.ext.autosummary

diff --git a/docs/source/docs/level-up/advanced_skills/index.rst b/docs/source/docs/level-up/advanced_skills/index.rst
@@ -1,5 +1,5 @@
 Advanced Skills
-###########
+###############
 
 .. panels::
 

diff --git a/docs/source/docs/level-up/basic_skills/index.rst b/docs/source/docs/level-up/basic_skills/index.rst
@@ -1,5 +1,5 @@
 Basic Skills
-###########
+############
 
 .. panels::
 

diff --git a/docs/source/docs/level-up/intermediate_skills/index.rst b/docs/source/docs/level-up/intermediate_skills/index.rst
@@ -1,5 +1,5 @@
 Intermediate Skills
-###########
+###################
 
 .. panels::
 

diff --git a/...erence/plugins/sampler/algorithm/datumaro.plugins.sampler.algorithm.entropy.rst b/...erence/plugins/sampler/algorithm/datumaro.plugins.sampler.algorithm.entropy.rst
@@ -2,13 +2,6 @@ Entropy module
 --------------
 
 .. automodule:: datumaro.plugins.sampler.algorithm.entropy
-
-   .. autoclass:: SampleEntropy
-
-      .. automethod:: __init__
-
-      .. automethod:: get_sample
-
-      .. automethod:: _get_sample_mixed
-
-      .. automethod:: _rank_images
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/...docs/reference/plugins/sampler/algorithm/datumaro.plugins.sampler.algorithm.rst b/...docs/reference/plugins/sampler/algorithm/datumaro.plugins.sampler.algorithm.rst
@@ -5,4 +5,3 @@ Algorithm module
    :members:
    :undoc-members:
    :show-inheritance:
-   :private-members:
diff --git a/docs/source/docs/user-manual/extending.md b/docs/source/docs/user-manual/extending.md
@@ -1,8 +1,8 @@
 # Extending
 
 There are few ways to extend and customize Datumaro behavior, which is
-supported by plugins. Check [our contribution guide](/docs/contributing) for
-details on plugin implementation. In general, a plugin is a Python module.
+supported by plugins. Check [our contribution guide](https://github.com/openvinotoolkit/datumaro/blob/develop/contributing.md)
+for details on plugin implementation. In general, a plugin is a Python module.
 It must be put into a plugin directory:
 - `<project_dir>/.datumaro/plugins` for project-specific plugins
 - `<datumaro_dir>/plugins` for global plugins

diff --git a/notebooks/09_encrypt_dataset.ipynb b/notebooks/09_encrypt_dataset.ipynb
@@ -315,7 +315,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Re-export again to any dataset format with no encryption\n",
+    "## Re-export again to any dataset format with no encryption\n",
     "\n",
     "Because the `DatumaroBinary` format is encrypted, it cannot be easily used for your purposes. In this time, we re-export it to any dataset format for the future usage. For example, COCO format is used for the export."
    ]

diff --git a/requirements.txt b/requirements.txt
@@ -2,8 +2,3 @@
 -r requirements-default.txt
 
 opencv-python-headless>=4.1.0.25
-
-# docs
-markupsafe>=2.0.1
-nbconvert>=7.2.3
-ipython>=8.4.0
diff --git a/tox.ini b/tox.ini
@@ -2,10 +2,12 @@
 isolated_build = true
 skip_missing_interpreters = true
 
+
 [testenv]
 deps =
     -r{toxinidir}/requirements.txt
 
+
 [testenv:pre-commit]
 basepython = python3
 deps =