Resolved warnings during document generation. (#408)

* Resolve warning.

* Resolve warning.

* Add docstrfmt.

* Format by docstrfmt.

* Remove -s inc .

* Remove search-field .

* Fix for docstrfmt.

---------

Co-authored-by: Yoshiaki Bando <[email protected]>

.github/workflows/lint.yaml

@@ -29,3 +29,6 @@ jobs:
       - name: Perform mypy
         run: |
           mypy --config-file mypy.ini .
+      - name: Perform docstrfmt
+        run: |
+          docstrfmt --check docs/source/

docs/source/api_reference/hpo.rst

@@ -1,41 +1,48 @@
 Hyperparameter Optimization
 ===========================
 
-
 Algorithms
 ----------
 
 .. currentmodule:: aiaccel.hpo.algorithms
+
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
 
-   NelderMeadAlgorism
+    NelderMeadAlgorism
 
 Optuna Utilities
 ----------------
 
 Samplers
-^^^^^^^^
+~~~~~~~~
 
 .. currentmodule:: aiaccel.hpo.optuna.samplers
+
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
 
-   NelderMeadSampler
+    NelderMeadSampler
 
 Suggest Wrappers
-^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~
+
 .. currentmodule:: aiaccel.hpo.optuna.suggest_wrapper
+
 .. autosummary::
-   :toctree: generated/
-
-   Suggest
-   Const
-   SuggestFloat
-   SuggestInt
-   SuggestCategorical
-   SuggestDiscreteUniform
-   SuggestLogUniform
-   SuggestUniform
-..    lightning.OptimizerLightningModule
-..    lightning.OptimizerConfig
+    :toctree: generated/
+
+    Suggest
+    Const
+    SuggestFloat
+    SuggestInt
+    SuggestCategorical
+    SuggestDiscreteUniform
+    SuggestLogUniform
+    SuggestUniform
+
+..
+    lightning.OptimizerLightningModule
+
+..
+    lightning.OptimizerConfig

docs/source/api_reference/index.rst

@@ -1,12 +1,9 @@
-
-*************
 API Reference
-*************
-
+=============
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   torch
-   hpo
-   utils
+    torch
+    hpo
+    utils

docs/source/api_reference/torch.rst

@@ -1,32 +1,36 @@
 PyTorch/Lightning Toolkit
 =========================
 
-
 Datasets
 --------
+
 .. currentmodule:: aiaccel.torch.datasets
+
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
 
-   CachedDataset
-   HDF5Dataset
-   RawHDF5Dataset
+    CachedDataset
+    HDF5Dataset
+    RawHDF5Dataset
 
 Dataset Utilities
 -----------------
+
 .. currentmodule:: aiaccel.torch.datasets
-.. autosummary::
-   :toctree: generated/
 
-   scatter_dataset
+.. autosummary::
+    :toctree: generated/
 
+    scatter_dataset
 
 Lightning Utilities
 -------------------
+
 .. currentmodule:: aiaccel.torch.lightning
+
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
 
-   ABCIEnvironment
-   OptimizerLightningModule
-   OptimizerConfig
+    ABCIEnvironment
+    OptimizerLightningModule
+    OptimizerConfig

docs/source/api_reference/utils.rst

@@ -1,13 +1,13 @@
 Miscellaneous Utilities
 =======================
 
-
 Config Utilities
 ----------------
 
 .. currentmodule:: aiaccel.utils
+
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
 
-   print_config
-   pathlib2str_config
+    print_config
+    pathlib2str_config

docs/source/conf.py

@@ -39,7 +39,6 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
-    "sphinx_fontawesome",
     "myst_parser",
     "pydata_sphinx_theme",
     "sphinx.ext.doctest",
@@ -76,7 +75,7 @@
 html_show_sourcelink = False
 html_show_sphinx = False
 # (commentout) html_static_path = ["_static"]
-html_sidebars = {"**": ["search-field", "sidebar-nav-bs", "sourcelink.html"]}
+html_sidebars = {"**": ["sidebar-nav-bs", "sourcelink.html"]}
 source_suffix = {".rst": "restructuredtext", ".txt": "markdown", ".md": "markdown"}
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/source/contribution_guide/index.rst

@@ -1,11 +1,10 @@
 Contribution Guide
 ==================
 
-Thank you for contributing to aiaccel!
-This document introduces how to contribute.
+Thank you for contributing to aiaccel! This document introduces how to contribute.
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   issues
-   pull_requests
+    issues
+    pull_requests

docs/source/contribution_guide/issues.md

@@ -2,14 +2,14 @@
 When you find any problems or have requests for new features, please first check to ensure that there is no duplicate issues already posted.
 We usually use Japanese for internal development, but we are more than happy to communicate with you in English.
 
-### Bug report
+## Bug report
 A bug report should briefly summarize the following details:
 * What the bug is
 * Steps to reproduce the bug
 * What you expected to happen
 * The execution environment
 
-### Feature request
+## Feature request
 
 A feature request should briefly summarize the following details:
 

docs/source/contribution_guide/pull_requests.md

@@ -2,7 +2,7 @@
 
 When you want to the modified code to be reflected in the repository, please execute pull request.
 
-### Procedures
+## Procedures
 
 - Please fork aiaccel repository on GitHub.
 - After forking, run `git clone` command for aiaccel repository.
@@ -11,7 +11,7 @@ When you want to the modified code to be reflected in the repository, please exe
 git clone https://github.com/[YOUR USERNAME]/aiaccel.git
 ~~~
 
-### Development
+## Development
 - Update a local repository to the latest version.
 
 ~~~bash
@@ -31,16 +31,16 @@ git checkout -b feature/add-new-feature
   - The message should be written in such a way that their contents can be  understood without refering code.
 
 
-### Submitting
+## Submitting
 
 Before submit *Pull request*, confirm the following:
 - Did you discuss it with other developer on issues in advance?
 - Can it be distributed under the MIT licence?
-- Is there appropriate [unit tests](#test)?
-- Can the [unit tests](#test) be run on local?
+- Is there appropriate [unit tests](test) ?
+- Can the [unit tests](test) be run on local?
 - Does the public function have a docstring?
-- Can the [documentation](#documentation-wip) be rendered correctly?
-- Is the [coding style](#coding-style) appropriate?
+- Can the [documentation](documentation-wip) be rendered correctly?
+- Is the [coding style](coding-style) appropriate?
 - Is the commit message appropriate?
 - For larger commit, please provide the example (docs/source/examples) and the description of module level.
 - If you are adding complied codes, have you modified setup.py?
@@ -71,6 +71,7 @@ git push origin feature/add-new-feature
 - When updating codes in the pull request, please commit the changes in the local repository and push the changes to the fork only if they have been successfully tested in the local environment.
 - If the pull request has been reviewed and approved by at least one member of the aiaccel development team, it will be merged into the main branch.
 
+(documentation-wip)=
 # Documentation (WIP)
 
 ## Docstrings
@@ -110,6 +111,7 @@ make gettext
 sphinx-intl update -p build/gettext -l en -l ja
 ~~~
 
+(test)=
 # Test
 
 ## Adding tests
@@ -166,6 +168,7 @@ pytest --cov=aiaccel
 pytest --cov=aiaccel --cov-branch
 ~~~
 
+(coding-style)=
 # Coding style
 
 ## Basic rules

docs/source/index.rst

@@ -1,76 +1,71 @@
-.. aiaccel-dev documentation master file, created by
-   sphinx-quickstart on Mon Jan 18 15:46:13 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
+..
+    aiaccel-dev documentation master file, created by
+    sphinx-quickstart on Mon Jan 18 15:46:13 2021.
+    You can adapt this file completely to your liking, but it should at least
+    contain the root `toctree` directive.
 
 Aiaccel
 =======
 
 AIST toolkit for accelerating machine learning research.
 
-
 :octicon:`cpu;1em;sd-text-primary` High-Performance Computing (HPC)
-   Intended to use in the HPC clusters including AI Bridging Cloud Infrastructure (ABCI).
+    Intended to use in the HPC clusters including AI Bridging Cloud Infrastructure
+    (ABCI).
 
 :octicon:`server;1em;sd-text-primary` Highly Modular Design
-   Designed to let you pick up any part of aiaccel with minimal dependencies as you prefer.
+    Designed to let you pick up any part of aiaccel with minimal dependencies as you
+    prefer.
 
 :octicon:`zap;1em;sd-text-primary` High Compatibility
-   Compatible with the modern standard frameworks such as PyTorch Lightning and Optuna.
-
+    Compatible with the modern standard frameworks such as PyTorch Lightning and Optuna.
 
 .. grid::
 
-   .. grid-item-card:: PyTorch/Lightning Toolkit
-      :link: api_reference/torch.html
-
-      Training toolkit for HPC clusters.
+    .. grid-item-card:: PyTorch/Lightning Toolkit
+       :link: api_reference/torch.html
 
-   .. grid-item-card:: Hyperparameter Optimization (HPO)
-      :link: api_reference/hpo.html
-
-      Ready-to-use HPO algorithms/tools.
+       Training toolkit for HPC clusters.
 
+    .. grid-item-card:: Hyperparameter Optimization (HPO)
+       :link: api_reference/hpo.html
 
+       Ready-to-use HPO algorithms/tools.
 
 Getting Started
---------
+---------------
 
 .. toctree::
-   :maxdepth: 2
-
-   getting_started.md
+    :maxdepth: 2
 
+    getting_started.md
 
 User Guide
---------
+----------
 
 .. toctree::
-   :maxdepth: 2
-
-   user_guide/index.rst
+    :maxdepth: 2
 
+    user_guide/index.rst
 
 API Reference
---------
-
+-------------
 
 .. toctree::
-   :maxdepth: 2
-
-   api_reference/index.rst
+    :maxdepth: 2
 
+    api_reference/index.rst
 
 Contribution Guide
---------
+------------------
 
 .. toctree::
-   :maxdepth: 2
-
-   contribution_guide/index.rst
+    :maxdepth: 2
 
+    contribution_guide/index.rst
 
 Acknowledgments
---------
-* Part of this work was developed under a commissioned project of the New Energy and Industrial Technology Development Organization (NEDO).
+---------------
+
+- Part of this work was developed under a commissioned project of the New Energy and
+  Industrial Technology Development Organization (NEDO).