docs: update documentation structure

.vscode/settings.json

@@ -51,7 +51,6 @@
     "sphinxcontrib",
     "titlesonly",
     "toctree",
-    "togglebutton",
     "typer",
     "unshallow",
     "viewcode"

Makefile

@@ -117,7 +117,8 @@ publish:
 doc-autobuild:
 	pdm run python -m sphinx_autobuild docs $(PUBLIC_DIR) \
 		--watch README.md \
-		--watch src
+		--watch src \
+		-a
 
 # Generate changelog from git commits.
 # NOTE(xuan.hu): Need to be run before document generation to take effect.

docs/advanced/index.md

@@ -0,0 +1,8 @@
+# Advanced Usage
+
+This section provides recommended best practices for enhancing your development workflow. While not essential, these topics can optimize the project management and development processes.
+
+```{toctree}
+dev-containers
+partial-dev-env
+```

docs/advanced/partial-dev-env.md

@@ -0,0 +1,55 @@
+# Partially Set Up Development Environment
+
+In certain cases, it is unnecessary to install all dependencies as well as the pre-commit hook. For example, this can speed up the setup process in CI/CD.
+
+## Minimal installation
+
+Install the project in editable mode with only the necessary dependencies, which is useful for scenarios like deployment.
+
+```bash
+make install
+```
+
+## Documentation generation
+
+Install the project in editable mode with dependencies related to `doc`,
+recommended for scenarios like the documentation generation CI/CD process.
+
+```bash
+make dev-doc
+```
+
+## Lint check
+
+Install the project in editable mode with dependencies related to `lint`,
+recommended for scenarios like the lint CI/CD process.
+
+```bash
+make dev-lint
+```
+
+## Package build
+
+Install the project in editable mode with dependencies related to `package`,
+recommended for scenarios like the package CI/CD process.
+
+```bash
+make dev-package
+```
+
+## Testing
+
+Install the project in editable mode with dependencies related to `test`,
+recommended for scenarios like the test CI/CD process.
+
+```bash
+make dev-test
+```
+
+## Combination
+
+To install dependencies for `doc` and `lint`, use the following command:
+
+```bash
+make dev-doc,lint
+```

docs/conf.py

@@ -26,7 +26,6 @@
     "sphinx.ext.viewcode",
     "sphinx_click",
     "sphinx_design",
-    "sphinx_togglebutton",
     "sphinxcontrib.autodoc_pydantic",
 ]
 source_suffix = {

docs/development/cleanup-dev-env.md

@@ -0,0 +1,31 @@
+# Clean Up Development Environment
+
+When encountering environment-related problems, a straightforward solution is to cleanup the environment and setup a new one. Three different levels of cleanup approach are provided here.
+
+## Intermediate cleanup
+
+Intermediate cleanup only removes common intermediate files, such as generated documentation, package, coverage report, cache files for mypy, pytest, ruff and so on.
+
+```bash
+make clean
+```
+
+## Deep cleanup
+
+Deep cleanup removes the pre-commit hook and the virtual environment alongside the common intermediate files.
+
+```bash
+make deepclean
+```
+
+## Complete cleanup
+
+Complete cleanup restores the repository to its original, freshly-cloned state, ideal for starting over from scratch.
+
+```{caution}
+This will remove all untracked files, please use it with caution. It is recommended to check with dry-run mode (`git clean -dfnx`) before actually removing anything. For more information, please refer to the [git-clean documentation](https://git-scm.com/docs/git-clean).
+```
+
+```bash
+git clean -dfx
+```

docs/dev/commit.md → docs/development/commit.md

@@ -47,7 +47,7 @@ For more details, please refer to [the Angular convention](https://pawamoy.githu
 ## Commit in Development Branches
 
 While the commit convention seems strict, we aim for flexibility during the development phase.
-By adhering to the [project configuration](proj.md#project-configuration), all changes should be introduced via pull/merge requests.
+By adhering to the [project configuration](../management/config.md), all changes should be introduced via pull/merge requests.
 Using the squash merge strategy, the emphasis is primarily on the title of pull/merge requests.
 In this way, individual commit within development branches does not need to strictly adhere to the commit convention.
 

docs/development/index.md

@@ -0,0 +1,9 @@
+# Development Practices
+
+This section is designed for developers and covers essential topics during daily development lifecycle. Follow these guidelines to ensure all contributors adhere to best practices, maintain code quality, and collaborate efficiently.
+
+```{toctree}
+setup-dev-env
+cleanup-dev-env
+commit
+```

docs/development/setup-dev-env.md

@@ -0,0 +1,35 @@
+# Set Up Development Environment
+
+This page shows the approach to set up development environment. To simplify the process, a unified `Makefile` is maintained at the root directory of the repo. In other words, all the `make` related commands are supposed to run there.
+
+## Prerequisites
+
+Several necessary tools need to be installed with the following commands:
+
+```{note}
+Using `pipx` for management is recommended and you can find pipx's installation instructions [here](https://pypa.github.io/pipx/installation/).
+```
+
+```bash
+# PDM: A modern Python package and dependency manager supporting the latest PEP standards.
+pipx install pdm==2.15.2
+# Pre-commit: Automates Git hooks for code quality checks.
+pipx install pre-commit==3.7.1
+```
+
+## Setup
+
+Development environment can be setup with the following command:
+
+```bash
+make dev
+```
+
+This command will accomplish the following tasks:
+
+- Create a virtual environment.
+- Install all the dependencies, including those for documentation, lint, package and test.
+- Install the project in editable mode.
+- Install git hook scripts for `pre-commit`.
+
+To speed up the setup process in certain scenarios, you may find <project:../advanced/partial-dev-env.md> helpful.

docs/index.md

@@ -3,7 +3,9 @@
 ```{toctree}
 :hidden:
 Overview <self>
-dev/index
+management/index
+development/index
+advanced/index
 cli/index
 api/index
 reports/index