From c5685326a3b8ef9d8417d2a48e60c79c1a4f9ed1 Mon Sep 17 00:00:00 2001 From: KanaiYuma Date: Wed, 18 Dec 2024 10:23:06 +0900 Subject: [PATCH 1/5] Resolve warning. --- docs/source/conf.py | 1 - docs/source/contribution_guide/issues.md | 4 ++-- docs/source/contribution_guide/pull_requests.md | 17 ++++++++++------- docs/source/index.rst | 10 +++++----- 4 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 250353fa..98152374 100644 --- a/docs/source/conf.py +++ b/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", diff --git a/docs/source/contribution_guide/issues.md b/docs/source/contribution_guide/issues.md index 79b1e284..d4557925 100644 --- a/docs/source/contribution_guide/issues.md +++ b/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: diff --git a/docs/source/contribution_guide/pull_requests.md b/docs/source/contribution_guide/pull_requests.md index 17eb0979..32f6eaa6 100644 --- a/docs/source/contribution_guide/pull_requests.md +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 8f9409f3..cd9aa850 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -35,7 +35,7 @@ AIST toolkit for accelerating machine learning research. Getting Started --------- +---------------- .. toctree:: :maxdepth: 2 @@ -44,7 +44,7 @@ Getting Started User Guide --------- +----------- .. toctree:: :maxdepth: 2 @@ -53,7 +53,7 @@ User Guide API Reference --------- +-------------- .. toctree:: @@ -63,7 +63,7 @@ API Reference Contribution Guide --------- +------------------- .. toctree:: :maxdepth: 2 @@ -72,5 +72,5 @@ Contribution Guide Acknowledgments --------- +---------------- * Part of this work was developed under a commissioned project of the New Energy and Industrial Technology Development Organization (NEDO). From 6c09b187fce2ec7adc23727e92ffd0a5465de8ca Mon Sep 17 00:00:00 2001 From: KanaiYuma Date: Wed, 18 Dec 2024 11:09:32 +0900 Subject: [PATCH 2/5] Resolve warning. --- .github/workflows/publish_pages.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish_pages.yaml b/.github/workflows/publish_pages.yaml index 28ad6f5e..6146db01 100644 --- a/.github/workflows/publish_pages.yaml +++ b/.github/workflows/publish_pages.yaml @@ -18,7 +18,7 @@ jobs: python -m pip install .[dev,github-actions,test] - name: Sphinx build run: | - sphinx-apidoc --maxdepth 2 -f -o ./docs/source/api_reference/ ./aiaccel/ + sphinx-apidoc --maxdepth 2 -f -o ./docs/source/api_reference/ -s inc ./aiaccel/ cd docs make html - name: Deploy to GitHub Pages From a23b7162b9387b765432781755f13cfc1d29fcb7 Mon Sep 17 00:00:00 2001 From: KanaiYuma Date: Thu, 19 Dec 2024 11:17:13 +0900 Subject: [PATCH 3/5] Add docstrfmt. --- .github/workflows/lint.yaml | 3 +++ setup.py | 1 + 2 files changed, 4 insertions(+) diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index 348c520e..beb58aeb 100644 --- a/.github/workflows/lint.yaml +++ b/.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/ diff --git a/setup.py b/setup.py index c022a994..2e178b55 100644 --- a/setup.py +++ b/setup.py @@ -26,6 +26,7 @@ "pandas", "pandas-stubs", "matplotlib", + "docstrfmt", ] github_actions_dependencies = [ "pytest-github-actions-annotate-failures", From a4a41c1e2d9a784e292f33cf0bab7db7445b69fd Mon Sep 17 00:00:00 2001 From: KanaiYuma Date: Thu, 19 Dec 2024 14:01:07 +0900 Subject: [PATCH 4/5] Format by docstrfmt. --- docs/source/api_reference/hpo.rst | 45 +++++++++------- docs/source/api_reference/index.rst | 13 ++--- docs/source/api_reference/torch.rst | 28 +++++----- docs/source/api_reference/utils.rst | 8 +-- docs/source/contribution_guide/index.rst | 9 ++-- docs/source/index.rst | 69 +++++++++++------------- docs/source/user_guide/hpo.rst | 3 +- docs/source/user_guide/index.rst | 10 ++-- docs/source/user_guide/torch.rst | 2 - 9 files changed, 94 insertions(+), 93 deletions(-) diff --git a/docs/source/api_reference/hpo.rst b/docs/source/api_reference/hpo.rst index 963c92a0..ba09f626 100644 --- a/docs/source/api_reference/hpo.rst +++ b/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 \ No newline at end of file + :toctree: generated/ + + Suggest + Const + SuggestFloat + SuggestInt + SuggestCategorical + SuggestDiscreteUniform + SuggestLogUniform + SuggestUniform + +.. + lightning.OptimizerLightningModule + +.. + lightning.OptimizerConfig diff --git a/docs/source/api_reference/index.rst b/docs/source/api_reference/index.rst index f1d204dc..77a4c4ae 100644 --- a/docs/source/api_reference/index.rst +++ b/docs/source/api_reference/index.rst @@ -1,12 +1,9 @@ - -************* API Reference -************* - +============= .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - torch - hpo - utils \ No newline at end of file + torch + hpo + utils diff --git a/docs/source/api_reference/torch.rst b/docs/source/api_reference/torch.rst index e90c0962..3bab48fb 100644 --- a/docs/source/api_reference/torch.rst +++ b/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 diff --git a/docs/source/api_reference/utils.rst b/docs/source/api_reference/utils.rst index a67f286a..cae69914 100644 --- a/docs/source/api_reference/utils.rst +++ b/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 diff --git a/docs/source/contribution_guide/index.rst b/docs/source/contribution_guide/index.rst index 36a7cf24..9caffa59 100644 --- a/docs/source/contribution_guide/index.rst +++ b/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 \ No newline at end of file + issues + pull_requests diff --git a/docs/source/index.rst b/docs/source/index.rst index cd9aa850..4e61f7d5 100644 --- a/docs/source/index.rst +++ b/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). diff --git a/docs/source/user_guide/hpo.rst b/docs/source/user_guide/hpo.rst index 487db7b3..79cb5edd 100644 --- a/docs/source/user_guide/hpo.rst +++ b/docs/source/user_guide/hpo.rst @@ -1,6 +1,7 @@ Optimizing Your Hyperparameters =============================== -Hyperparameter optimization (HPO) is an indispensable step to make it work in real world. +Hyperparameter optimization (HPO) is an indispensable step to make it work in real +world. (WIP) diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst index f18378e3..9d540549 100644 --- a/docs/source/user_guide/index.rst +++ b/docs/source/user_guide/index.rst @@ -1,8 +1,8 @@ User Guide -================== +========== .. toctree:: - :maxdepth: 2 - - torch - hpo \ No newline at end of file + :maxdepth: 2 + + torch + hpo diff --git a/docs/source/user_guide/torch.rst b/docs/source/user_guide/torch.rst index e4ee80c0..0c488e4a 100644 --- a/docs/source/user_guide/torch.rst +++ b/docs/source/user_guide/torch.rst @@ -7,10 +7,8 @@ Writing a simple training script Running inference ----------------- - Writing a DDP training script ----------------------------- - Accelerating your training -------------------------- From a7a90462e7cde88215e93d0d0ac25d8f5100df05 Mon Sep 17 00:00:00 2001 From: KanaiYuma Date: Mon, 6 Jan 2025 15:04:00 +0900 Subject: [PATCH 5/5] Remove -s inc . --- .github/workflows/publish_pages.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish_pages.yaml b/.github/workflows/publish_pages.yaml index 2a6ffe39..20e0f8e9 100644 --- a/.github/workflows/publish_pages.yaml +++ b/.github/workflows/publish_pages.yaml @@ -18,7 +18,7 @@ jobs: python -m pip install .[all_dev] - name: Sphinx build run: | - sphinx-apidoc --maxdepth 2 -f -o ./docs/source/api_reference/ -s inc ./aiaccel/ + sphinx-apidoc --maxdepth 2 -f -o ./docs/source/api_reference/ ./aiaccel/ cd docs make html - name: Deploy to GitHub Pages