From e6f824a361359510cfd2b7482f3c77ff57af7c29 Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Thu, 16 May 2024 17:35:32 +0800 Subject: [PATCH 1/4] doc: update documentation structure --- .vscode/settings.json | 1 - Makefile | 3 +- docs/{dev => advanced}/dev-containers.md | 0 docs/advanced/index.md | 8 ++ docs/advanced/partial-dev-env.md | 55 +++++++++ docs/conf.py | 1 - docs/dev/dev-env.md | 124 --------------------- docs/dev/index.md | 27 ----- docs/development/cleanup-dev-env.md | 31 ++++++ docs/{dev => development}/commit.md | 2 +- docs/development/index.md | 9 ++ docs/development/setup-dev-env.md | 35 ++++++ docs/index.md | 4 +- docs/{dev/proj.md => management/config.md} | 107 +----------------- docs/management/index.md | 10 ++ docs/management/init.md | 48 ++++++++ docs/{dev => management}/release.md | 4 +- docs/management/update.md | 22 ++++ pdm.lock | 40 +------ pyproject.toml | 1 - template/.vscode/settings.json | 1 - template/docs/conf.py.jinja | 1 - template/pyproject.toml.jinja | 1 - 23 files changed, 228 insertions(+), 307 deletions(-) rename docs/{dev => advanced}/dev-containers.md (100%) create mode 100644 docs/advanced/index.md create mode 100644 docs/advanced/partial-dev-env.md delete mode 100644 docs/dev/dev-env.md delete mode 100644 docs/dev/index.md create mode 100644 docs/development/cleanup-dev-env.md rename docs/{dev => development}/commit.md (95%) create mode 100644 docs/development/index.md create mode 100644 docs/development/setup-dev-env.md rename docs/{dev/proj.md => management/config.md} (67%) create mode 100644 docs/management/index.md create mode 100644 docs/management/init.md rename docs/{dev => management}/release.md (95%) create mode 100644 docs/management/update.md diff --git a/.vscode/settings.json b/.vscode/settings.json index eb4be3ee..ea1ce1ad 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -51,7 +51,6 @@ "sphinxcontrib", "titlesonly", "toctree", - "togglebutton", "typer", "unshallow", "viewcode" diff --git a/Makefile b/Makefile index 896028f2..93a1bbe6 100644 --- a/Makefile +++ b/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. diff --git a/docs/dev/dev-containers.md b/docs/advanced/dev-containers.md similarity index 100% rename from docs/dev/dev-containers.md rename to docs/advanced/dev-containers.md diff --git a/docs/advanced/index.md b/docs/advanced/index.md new file mode 100644 index 00000000..a48434c2 --- /dev/null +++ b/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 +``` diff --git a/docs/advanced/partial-dev-env.md b/docs/advanced/partial-dev-env.md new file mode 100644 index 00000000..467b14fb --- /dev/null +++ b/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, speed up the setup process in CI/CD. + +## Minimal installation + +Install the project in editable mode only with necessary dependencies, useful for scenarios like deployment. + +```bash +make install +``` + +## Documentation generation + +Install the project in editable mode with `doc` related dependencies, +recommended for scenarios like documentation generation CI/CD process. + +```bash +make dev-doc +``` + +## Lint check + +Install the project in editable mode with `lint` related dependencies, +recommended for scenarios like lint CI/CD process. + +```bash +make dev-lint +``` + +## Package build + +Install the project in editable mode with `package` related dependencies, +recommended for scenarios like package CI/CD process. + +```bash +make dev-package +``` + +## Testing + +Install the project in editable mode with `test` related dependencies, +recommended for scenarios like test CI/CD process. + +```bash +make dev-test +``` + +## Combination + +For example, to install dependencies for `doc` and `lint`, we can use the following command. + +```bash +make dev-doc,lint +``` diff --git a/docs/conf.py b/docs/conf.py index 8c27f7d2..ce74b712 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,7 +26,6 @@ "sphinx.ext.viewcode", "sphinx_click", "sphinx_design", - "sphinx_togglebutton", "sphinxcontrib.autodoc_pydantic", ] source_suffix = { diff --git a/docs/dev/dev-env.md b/docs/dev/dev-env.md deleted file mode 100644 index fead4046..00000000 --- a/docs/dev/dev-env.md +++ /dev/null @@ -1,124 +0,0 @@ -# Development Environment - -This page shows the approach to manage 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 - -After generating the project via `copier`, several necessary tools can 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 helpful. - -## Cleanup - -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 -``` - -## Partial Setup - -In certain cases, it is unnecessary to install all dependencies as well as the pre-commit hook. For example, speed up the setup process in CI/CD. - -### Minimal installation - -Install the project in editable mode only with necessary dependencies, useful for scenarios like deployment. - -```bash -make install -``` - -### Documentation generation - -Install the project in editable mode with `doc` related dependencies, -recommended for scenarios like documentation generation CI/CD process. - -```bash -make dev-doc -``` - -### Lint check - -Install the project in editable mode with `lint` related dependencies, -recommended for scenarios like lint CI/CD process. - -```bash -make dev-lint -``` - -### Package build - -Install the project in editable mode with `package` related dependencies, -recommended for scenarios like package CI/CD process. - -```bash -make dev-package -``` - -### Testing - -Install the project in editable mode with `test` related dependencies, -recommended for scenarios like test CI/CD process. - -```bash -make dev-test -``` - -````{admonition} Install a combination of the optional dependencies -:class: tip, dropdown -For example, to install dependencies for `doc` and `lint`, we can use the following command. - -```bash -make dev-doc,lint -``` -```` diff --git a/docs/dev/index.md b/docs/dev/index.md deleted file mode 100644 index e8f7c7b9..00000000 --- a/docs/dev/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# Development - -This section is a comprehensive guide that spans various aspects of the development lifecycle. From the initial phases of **project and environment management**, to maintaining a clear **commit convention**, and culminating in the **release process**, we aim to establish best practices for modest-sized Python projects and teams, suitable for both open-source platforms like GitHub/GitLab, as well as self-managed GitLab repositories. - -```{note} -Best practices can vary based on specific circumstances. We are open to comments and suggestions to refine the approach. -``` - -```{toctree} -:hidden: -proj -dev-env -dev-containers -commit -release -``` - -## For Developers - -- -- -- - -## For Maintainers - -- -- diff --git a/docs/development/cleanup-dev-env.md b/docs/development/cleanup-dev-env.md new file mode 100644 index 00000000..d4057a9a --- /dev/null +++ b/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 +``` diff --git a/docs/dev/commit.md b/docs/development/commit.md similarity index 95% rename from docs/dev/commit.md rename to docs/development/commit.md index 3567b0cc..f18c6653 100644 --- a/docs/dev/commit.md +++ b/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. diff --git a/docs/development/index.md b/docs/development/index.md new file mode 100644 index 00000000..24b46c53 --- /dev/null +++ b/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 +``` diff --git a/docs/development/setup-dev-env.md b/docs/development/setup-dev-env.md new file mode 100644 index 00000000..1c8a7007 --- /dev/null +++ b/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 helpful. diff --git a/docs/index.md b/docs/index.md index 846ab4d7..cf28b011 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,9 @@ ```{toctree} :hidden: Overview -dev/index +management/index +development/index +advanced/index cli/index api/index reports/index diff --git a/docs/dev/proj.md b/docs/management/config.md similarity index 67% rename from docs/dev/proj.md rename to docs/management/config.md index 61c78745..64c4fcfc 100644 --- a/docs/dev/proj.md +++ b/docs/management/config.md @@ -1,86 +1,4 @@ -# Project Management - -## Prerequisites - -[`copier`](https://copier.readthedocs.io/) serves as a key tool in `serious-scaffold`, differentiating it from other project templates. The installation can be done with the following command. - -```{note} -Using `pipx` for management is recommended and you can find pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). -``` - -```bash -# Copier: Template rendering for projects. -pipx install copier==9.2.0 -``` - -## Project Initialization - -1. Create a Git repository on the hosting platform. Clone it to local and navigate to the root directory. - - ```{note} - The provided repository URL, `git@git.example.com/demo_namespace/demo_name.git`, is purely for demonstration purposes. - ``` - - ```bash - git clone git@git.example.com/demo_namespace/demo_name.git - cd demo_name - ``` - -1. Generate the project. - - ```{note} - Several questions will be prompted during this process. Your patience is appreciated for this one-time job. - ``` - - ```bash - copier copy gh:serious-scaffold/ss-python . - ``` - -1. Set up the development environment. - - ```bash - make dev - ``` - -1. Commit and push the initialized project. - - ```bash - git add . - git commit -m "chore: Initialize from ss-python." - SKIP=no-commit-to-branch git push - ``` - -1. Bootstrap the dev container. - - ::::{tab-set} - - :::{tab-item} GitHub - :sync: github - Navigate to the [Dev Container Workflow](https://github.com/serious-scaffold/ss-python/actions/workflows/devcontainer.yml) page and run workflow from the default branch. The container will be named following pattern `ghcr.io/serious-scaffold/ss-python/dev:py`, for example, `ghcr.io/serious-scaffold/ss-python/dev:py3.12`. - - ```{image} /_static/images/bootstrap-dev-container-github.png - :alt: Bootstrap Dev Container on GitHub. - :target: https://github.com/serious-scaffold/ss-python/actions/workflows/devcontainer.yml - ``` - - ::: - - :::{tab-item} GitLab - :sync: gitlab - Navigate to the [Run pipeline](https://gitlab.com/serious-scaffold/ss-python/-/pipelines/new) page and run pipeline for the default branch. The container will be named following pattern `registry.gitlab.com/serious-scaffold/ss-python/dev:py`, for example, `registry.gitlab.com/serious-scaffold/ss-python/dev:py3.12`. - - ```{image} /_static/images/bootstrap-dev-container-gitlab.png - :alt: Bootstrap Dev Container on GitLab. - :target: https://gitlab.com/serious-scaffold/ss-python/-/pipelines/new - ``` - - ::: - - :::: - -Now, everything is done for initialization. - -## Project Configuration +# Repository Configuration There are several configurations to utilize the features provided by the project template. These are only the essential ones, you can adjust according to your project's actual needs. @@ -170,26 +88,3 @@ You can set the scope of the variables and secrets to **Repository** or **Organi ::: :::: - -## Project Update - -Thanks to the update mechanism provided natively by `copier`, when a new version of the template is released, you can easily update the project. Just run the following command under the root directory: - -```bash -copier update -``` - -```{note} -The `-A/--skip-answered` flag can be used to skip questions that have already been answered. -``` - -In most cases, `copier` will manage updates seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. - -```{tip} -To minimize potential conflicts, there are several suggestions to follow: -1. Avoid modifying the auto-generated files unless absolutely necessary. -1. For template-related changes, consider proposing an issue or change request directly to the template repository. -1. For project-specific changes, adopt an inheritance or extension approach to minimize the changes to auto-generated contents. -``` - -For more details, please refer to `copier update --help` and [the official documentation](https://copier.readthedocs.io/en/stable/updating/). diff --git a/docs/management/index.md b/docs/management/index.md new file mode 100644 index 00000000..a097879c --- /dev/null +++ b/docs/management/index.md @@ -0,0 +1,10 @@ +# Project Management + +This section is designed for project maintainers and covers essential tasks for managing your project. Follow these guidelines to ensure your project remains up-to-date and adheres to best practices. + +```{toctree} +init +config +update +release +``` diff --git a/docs/management/init.md b/docs/management/init.md new file mode 100644 index 00000000..b4fd4d86 --- /dev/null +++ b/docs/management/init.md @@ -0,0 +1,48 @@ +# Project Initialization + +## Prerequisites + +Install [copier](https://copier.readthedocs.io/) for template operations. It is recommended to install via [pipx](https://pipx.pypa.io/) with the following command: + +```{note} +Find pipx installation instruction [here](https://pipx.pypa.io/stable/installation/). +``` + +```bash +pipx install copier==9.2.0 +``` + +## Create the Repository + +Create a blank Git repository on the hosting platform. Clone it locally and navigate to the root directory: + +```bash +git clone git@github.com/serious-scaffold/ss-python.git +cd ss-python +``` + +## Generate the Project + +Running the following command and answer the prompts to set up the project: + +```bash +copier copy gh:serious-scaffold/ss-python . +``` + +## Set Up Development Environment + +Set up development environment to prepare for the initial commit: + +```bash +make dev +``` + +## Commit and push + +```bash +git add . +git commit -m "chore: init from serious-scaffold-python" +SKIP=no-commit-to-branch git push +``` + +Now, everything is done! diff --git a/docs/dev/release.md b/docs/management/release.md similarity index 95% rename from docs/dev/release.md rename to docs/management/release.md index bdceb471..c4ba5f83 100644 --- a/docs/dev/release.md +++ b/docs/management/release.md @@ -54,5 +54,5 @@ Releasing a new version based on an old commit can be useful in scenarios where ## Guidelines 1. **Valid Release Tags:** Ensure that tags are not only compatible with semantic versioning but also unique and represent a version that is newer than any previously released. -1. **Commit Convention:** While not mandatory, it is beneficial to ensure an informative changelog by following the [Commit Convention](commit.md#commit-message-pattern) so that corresponding commit messages can be included in the changelog. -1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the [project configuration](proj.md#project-configuration). +1. **Commit Convention:** While not mandatory, it is beneficial to ensure an informative changelog by following the [Commit Convention](../development/commit.md#commit-message-pattern) so that corresponding commit messages can be included in the changelog. +1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the [project configuration](./config.md). diff --git a/docs/management/update.md b/docs/management/update.md new file mode 100644 index 00000000..535ebf2f --- /dev/null +++ b/docs/management/update.md @@ -0,0 +1,22 @@ +# Template Update + +Thanks to the update mechanism provided natively by `copier`, when a new version of the template is released, you can easily update the project. Just run the following command under the root directory: + +```bash +copier update +``` + +```{note} +The `-A/--skip-answered` flag can be used to skip questions that have already been answered. +``` + +In most cases, `copier` will manage updates seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. + +```{tip} +To minimize potential conflicts, there are several suggestions to follow: +1. Avoid modifying the auto-generated files unless absolutely necessary. +1. For template-related changes, consider proposing an issue or change request directly to the template repository. +1. For project-specific changes, adopt an inheritance or extension approach to minimize the changes to auto-generated contents. +``` + +For more details, please refer to `copier update --help` and [the official documentation](https://copier.readthedocs.io/en/stable/updating/). diff --git a/pdm.lock b/pdm.lock index 083c9f85..dc0e4837 100644 --- a/pdm.lock +++ b/pdm.lock @@ -5,7 +5,7 @@ groups = ["default", "doc", "lint", "test"] strategy = ["cross_platform", "inherit_metadata"] lock_version = "4.4.1" -content_hash = "sha256:45ec5c321b8ce19fd9b454e51079a824f63141ad15f39bee67a7f000f91f72fd" +content_hash = "sha256:4fd9aa4e9711a299952841fa37180e053cc68269432fa66fcfa32cf20fee9b29" [[package]] name = "alabaster" @@ -1011,17 +1011,6 @@ files = [ {file = "semver-3.0.2.tar.gz", hash = "sha256:6253adb39c70f6e51afed2fa7152bcd414c411286088fb4b9effb133885ab4cc"}, ] -[[package]] -name = "setuptools" -version = "69.0.2" -requires_python = ">=3.8" -summary = "Easily download, build, install, upgrade, and uninstall Python packages" -groups = ["doc"] -files = [ - {file = "setuptools-69.0.2-py3-none-any.whl", hash = "sha256:1e8fdff6797d3865f37397be788a4e3cba233608e9b509382a2777d25ebde7f2"}, - {file = "setuptools-69.0.2.tar.gz", hash = "sha256:735896e78a4742605974de002ac60562d286fa8051a7e2299445e8e8fbb01aa6"}, -] - [[package]] name = "shellingham" version = "1.5.4" @@ -1155,22 +1144,6 @@ files = [ {file = "sphinx_design-0.5.0.tar.gz", hash = "sha256:e8e513acea6f92d15c6de3b34e954458f245b8e761b45b63950f65373352ab00"}, ] -[[package]] -name = "sphinx-togglebutton" -version = "0.3.2" -summary = "Toggle page content and collapse admonitions in Sphinx." -groups = ["doc"] -dependencies = [ - "docutils", - "setuptools", - "sphinx", - "wheel", -] -files = [ - {file = "sphinx-togglebutton-0.3.2.tar.gz", hash = "sha256:ab0c8b366427b01e4c89802d5d078472c427fa6e9d12d521c34fa0442559dc7a"}, - {file = "sphinx_togglebutton-0.3.2-py3-none-any.whl", hash = "sha256:9647ba7874b7d1e2d43413d8497153a85edc6ac95a3fea9a75ef9c1e08aaae2b"}, -] - [[package]] name = "sphinxcontrib-applehelp" version = "1.0.4" @@ -1349,17 +1322,6 @@ files = [ {file = "urllib3-2.1.0.tar.gz", hash = "sha256:df7aa8afb0148fa78488e7899b2c59b5f4ffcfa82e6c54ccb9dd37c1d7b52d54"}, ] -[[package]] -name = "wheel" -version = "0.42.0" -requires_python = ">=3.7" -summary = "A built-package format for Python" -groups = ["doc"] -files = [ - {file = "wheel-0.42.0-py3-none-any.whl", hash = "sha256:177f9c9b0d45c47873b619f5b650346d632cdc35fb5e4d25058e09c9e581433d"}, - {file = "wheel-0.42.0.tar.gz", hash = "sha256:c45be39f7882c9d34243236f2d63cbd58039e360f85d0913425fbd7ceea617a8"}, -] - [[package]] name = "zipp" version = "3.17.0" diff --git a/pyproject.toml b/pyproject.toml index 75a90762..7c40307d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -85,7 +85,6 @@ doc = [ "sphinx-autobuild", "sphinx-click", "sphinx-design", - "sphinx-togglebutton", ] lint = [ "mypy", diff --git a/template/.vscode/settings.json b/template/.vscode/settings.json index eb4be3ee..ea1ce1ad 100644 --- a/template/.vscode/settings.json +++ b/template/.vscode/settings.json @@ -51,7 +51,6 @@ "sphinxcontrib", "titlesonly", "toctree", - "togglebutton", "typer", "unshallow", "viewcode" diff --git a/template/docs/conf.py.jinja b/template/docs/conf.py.jinja index 6520a2d6..e6c51948 100644 --- a/template/docs/conf.py.jinja +++ b/template/docs/conf.py.jinja @@ -26,7 +26,6 @@ extensions = [ "sphinx.ext.viewcode", "sphinx_click", "sphinx_design", - "sphinx_togglebutton", "sphinxcontrib.autodoc_pydantic", ] source_suffix = { diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index 7338d29d..d270fbb9 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -126,7 +126,6 @@ doc = [ "sphinx-autobuild", "sphinx-click", "sphinx-design", - "sphinx-togglebutton", ] lint = [ "mypy", From ffffe80768dbb7f95e528d7ee33b05d6ef8ffc0a Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Thu, 16 May 2024 18:16:29 +0800 Subject: [PATCH 2/4] update template --- template/Makefile.jinja | 3 +- .../{dev => advanced}/dev-containers.md.jinja | 0 template/docs/advanced/index.md | 8 ++ template/docs/advanced/partial-dev-env.md | 55 ++++++++ template/docs/dev/dev-env.md | 124 ------------------ template/docs/dev/index.md | 27 ---- template/docs/development/cleanup-dev-env.md | 31 +++++ template/docs/{dev => development}/commit.md | 2 +- template/docs/development/index.md | 9 ++ template/docs/development/setup-dev-env.md | 35 +++++ template/docs/index.md.jinja | 4 +- .../config.md.jinja} | 107 +-------------- template/docs/management/index.md | 10 ++ template/docs/management/init.md.jinja | 49 +++++++ .../docs/{dev => management}/release.md.jinja | 4 +- template/docs/management/update.md.jinja | 22 ++++ 16 files changed, 228 insertions(+), 262 deletions(-) rename template/docs/{dev => advanced}/dev-containers.md.jinja (100%) create mode 100644 template/docs/advanced/index.md create mode 100644 template/docs/advanced/partial-dev-env.md delete mode 100644 template/docs/dev/dev-env.md delete mode 100644 template/docs/dev/index.md create mode 100644 template/docs/development/cleanup-dev-env.md rename template/docs/{dev => development}/commit.md (95%) create mode 100644 template/docs/development/index.md create mode 100644 template/docs/development/setup-dev-env.md rename template/docs/{dev/proj.md.jinja => management/config.md.jinja} (67%) create mode 100644 template/docs/management/index.md create mode 100644 template/docs/management/init.md.jinja rename template/docs/{dev => management}/release.md.jinja (95%) create mode 100644 template/docs/management/update.md.jinja diff --git a/template/Makefile.jinja b/template/Makefile.jinja index 08415099..f5ec8191 100644 --- a/template/Makefile.jinja +++ b/template/Makefile.jinja @@ -119,7 +119,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. diff --git a/template/docs/dev/dev-containers.md.jinja b/template/docs/advanced/dev-containers.md.jinja similarity index 100% rename from template/docs/dev/dev-containers.md.jinja rename to template/docs/advanced/dev-containers.md.jinja diff --git a/template/docs/advanced/index.md b/template/docs/advanced/index.md new file mode 100644 index 00000000..a48434c2 --- /dev/null +++ b/template/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 +``` diff --git a/template/docs/advanced/partial-dev-env.md b/template/docs/advanced/partial-dev-env.md new file mode 100644 index 00000000..467b14fb --- /dev/null +++ b/template/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, speed up the setup process in CI/CD. + +## Minimal installation + +Install the project in editable mode only with necessary dependencies, useful for scenarios like deployment. + +```bash +make install +``` + +## Documentation generation + +Install the project in editable mode with `doc` related dependencies, +recommended for scenarios like documentation generation CI/CD process. + +```bash +make dev-doc +``` + +## Lint check + +Install the project in editable mode with `lint` related dependencies, +recommended for scenarios like lint CI/CD process. + +```bash +make dev-lint +``` + +## Package build + +Install the project in editable mode with `package` related dependencies, +recommended for scenarios like package CI/CD process. + +```bash +make dev-package +``` + +## Testing + +Install the project in editable mode with `test` related dependencies, +recommended for scenarios like test CI/CD process. + +```bash +make dev-test +``` + +## Combination + +For example, to install dependencies for `doc` and `lint`, we can use the following command. + +```bash +make dev-doc,lint +``` diff --git a/template/docs/dev/dev-env.md b/template/docs/dev/dev-env.md deleted file mode 100644 index fead4046..00000000 --- a/template/docs/dev/dev-env.md +++ /dev/null @@ -1,124 +0,0 @@ -# Development Environment - -This page shows the approach to manage 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 - -After generating the project via `copier`, several necessary tools can 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 helpful. - -## Cleanup - -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 -``` - -## Partial Setup - -In certain cases, it is unnecessary to install all dependencies as well as the pre-commit hook. For example, speed up the setup process in CI/CD. - -### Minimal installation - -Install the project in editable mode only with necessary dependencies, useful for scenarios like deployment. - -```bash -make install -``` - -### Documentation generation - -Install the project in editable mode with `doc` related dependencies, -recommended for scenarios like documentation generation CI/CD process. - -```bash -make dev-doc -``` - -### Lint check - -Install the project in editable mode with `lint` related dependencies, -recommended for scenarios like lint CI/CD process. - -```bash -make dev-lint -``` - -### Package build - -Install the project in editable mode with `package` related dependencies, -recommended for scenarios like package CI/CD process. - -```bash -make dev-package -``` - -### Testing - -Install the project in editable mode with `test` related dependencies, -recommended for scenarios like test CI/CD process. - -```bash -make dev-test -``` - -````{admonition} Install a combination of the optional dependencies -:class: tip, dropdown -For example, to install dependencies for `doc` and `lint`, we can use the following command. - -```bash -make dev-doc,lint -``` -```` diff --git a/template/docs/dev/index.md b/template/docs/dev/index.md deleted file mode 100644 index e8f7c7b9..00000000 --- a/template/docs/dev/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# Development - -This section is a comprehensive guide that spans various aspects of the development lifecycle. From the initial phases of **project and environment management**, to maintaining a clear **commit convention**, and culminating in the **release process**, we aim to establish best practices for modest-sized Python projects and teams, suitable for both open-source platforms like GitHub/GitLab, as well as self-managed GitLab repositories. - -```{note} -Best practices can vary based on specific circumstances. We are open to comments and suggestions to refine the approach. -``` - -```{toctree} -:hidden: -proj -dev-env -dev-containers -commit -release -``` - -## For Developers - -- -- -- - -## For Maintainers - -- -- diff --git a/template/docs/development/cleanup-dev-env.md b/template/docs/development/cleanup-dev-env.md new file mode 100644 index 00000000..d4057a9a --- /dev/null +++ b/template/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 +``` diff --git a/template/docs/dev/commit.md b/template/docs/development/commit.md similarity index 95% rename from template/docs/dev/commit.md rename to template/docs/development/commit.md index 3567b0cc..f18c6653 100644 --- a/template/docs/dev/commit.md +++ b/template/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. diff --git a/template/docs/development/index.md b/template/docs/development/index.md new file mode 100644 index 00000000..24b46c53 --- /dev/null +++ b/template/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 +``` diff --git a/template/docs/development/setup-dev-env.md b/template/docs/development/setup-dev-env.md new file mode 100644 index 00000000..1c8a7007 --- /dev/null +++ b/template/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 helpful. diff --git a/template/docs/index.md.jinja b/template/docs/index.md.jinja index 6162ed1e..57736396 100644 --- a/template/docs/index.md.jinja +++ b/template/docs/index.md.jinja @@ -3,7 +3,9 @@ ```{toctree} :hidden: Overview -dev/index +management/index +development/index +advanced/index cli/index api/index reports/index diff --git a/template/docs/dev/proj.md.jinja b/template/docs/management/config.md.jinja similarity index 67% rename from template/docs/dev/proj.md.jinja rename to template/docs/management/config.md.jinja index 93ceced9..8d09d9c7 100644 --- a/template/docs/dev/proj.md.jinja +++ b/template/docs/management/config.md.jinja @@ -1,86 +1,4 @@ -# Project Management - -## Prerequisites - -[`copier`](https://copier.readthedocs.io/) serves as a key tool in `serious-scaffold`, differentiating it from other project templates. The installation can be done with the following command. - -```{note} -Using `pipx` for management is recommended and you can find pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). -``` - -```bash -# Copier: Template rendering for projects. -pipx install copier==9.2.0 -``` - -## Project Initialization - -1. Create a Git repository on the hosting platform. Clone it to local and navigate to the root directory. - - ```{note} - The provided repository URL, `git@git.example.com/demo_namespace/demo_name.git`, is purely for demonstration purposes. - ``` - - ```bash - git clone git@git.example.com/demo_namespace/demo_name.git - cd demo_name - ``` - -1. Generate the project. - - ```{note} - Several questions will be prompted during this process. Your patience is appreciated for this one-time job. - ``` - - ```bash - copier copy gh:serious-scaffold/ss-python . - ``` - -1. Set up the development environment. - - ```bash - make dev - ``` - -1. Commit and push the initialized project. - - ```bash - git add . - git commit -m "chore: Initialize from ss-python." - SKIP=no-commit-to-branch git push - ``` - -1. Bootstrap the dev container. - - ::::{tab-set} - - :::{tab-item} GitHub - :sync: github - Navigate to the [Dev Container Workflow](https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/devcontainer.yml) page and run workflow from the default branch. The container will be named following pattern `ghcr.io/{{ repo_namespace }}/{{ repo_name }}/dev:py`, for example, `ghcr.io/{{ repo_namespace }}/{{ repo_name }}/dev:py3.12`. - - ```{image} /_static/images/bootstrap-dev-container-github.png - :alt: Bootstrap Dev Container on GitHub. - :target: https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/devcontainer.yml - ``` - - ::: - - :::{tab-item} GitLab - :sync: gitlab - Navigate to the [Run pipeline](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/pipelines/new) page and run pipeline for the default branch. The container will be named following pattern `registry.gitlab.com/{{ repo_namespace }}/{{ repo_name }}/dev:py`, for example, `registry.gitlab.com/{{ repo_namespace }}/{{ repo_name }}/dev:py3.12`. - - ```{image} /_static/images/bootstrap-dev-container-gitlab.png - :alt: Bootstrap Dev Container on GitLab. - :target: https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/pipelines/new - ``` - - ::: - - :::: - -Now, everything is done for initialization. - -## Project Configuration +# Repository Configuration There are several configurations to utilize the features provided by the project template. These are only the essential ones, you can adjust according to your project's actual needs. @@ -170,26 +88,3 @@ You can set the scope of the variables and secrets to **Repository** or **Organi ::: :::: - -## Project Update - -Thanks to the update mechanism provided natively by `copier`, when a new version of the template is released, you can easily update the project. Just run the following command under the root directory: - -```bash -copier update -``` - -```{note} -The `-A/--skip-answered` flag can be used to skip questions that have already been answered. -``` - -In most cases, `copier` will manage updates seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. - -```{tip} -To minimize potential conflicts, there are several suggestions to follow: -1. Avoid modifying the auto-generated files unless absolutely necessary. -1. For template-related changes, consider proposing an issue or change request directly to the template repository. -1. For project-specific changes, adopt an inheritance or extension approach to minimize the changes to auto-generated contents. -``` - -For more details, please refer to `copier update --help` and [the official documentation](https://copier.readthedocs.io/en/stable/updating/). diff --git a/template/docs/management/index.md b/template/docs/management/index.md new file mode 100644 index 00000000..a097879c --- /dev/null +++ b/template/docs/management/index.md @@ -0,0 +1,10 @@ +# Project Management + +This section is designed for project maintainers and covers essential tasks for managing your project. Follow these guidelines to ensure your project remains up-to-date and adheres to best practices. + +```{toctree} +init +config +update +release +``` diff --git a/template/docs/management/init.md.jinja b/template/docs/management/init.md.jinja new file mode 100644 index 00000000..62f0a1e8 --- /dev/null +++ b/template/docs/management/init.md.jinja @@ -0,0 +1,49 @@ +[% from pathjoin("includes", "variable.jinja") import repo_url with context -%] +# Project Initialization + +## Prerequisites + +Install [copier](https://copier.readthedocs.io/) for template operations. It is recommended to install via [pipx](https://pipx.pypa.io/) with the following command: + +```{note} +Find pipx installation instruction [here](https://pipx.pypa.io/stable/installation/). +``` + +```bash +pipx install copier==9.2.0 +``` + +## Create the Repository + +Create a blank Git repository on the hosting platform. Clone it locally and navigate to the root directory: + +```bash +git clone git@{{ repo_url() }}.git +cd {{ repo_name }} +``` + +## Generate the Project + +Running the following command and answer the prompts to set up the project: + +```bash +copier copy gh:serious-scaffold/ss-python . +``` + +## Set Up Development Environment + +Set up development environment to prepare for the initial commit: + +```bash +make dev +``` + +## Commit and push + +```bash +git add . +git commit -m "chore: init from serious-scaffold-python" +SKIP=no-commit-to-branch git push +``` + +Now, everything is done! diff --git a/template/docs/dev/release.md.jinja b/template/docs/management/release.md.jinja similarity index 95% rename from template/docs/dev/release.md.jinja rename to template/docs/management/release.md.jinja index 95f797ad..8d8b6bd8 100644 --- a/template/docs/dev/release.md.jinja +++ b/template/docs/management/release.md.jinja @@ -54,5 +54,5 @@ Releasing a new version based on an old commit can be useful in scenarios where ## Guidelines 1. **Valid Release Tags:** Ensure that tags are not only compatible with semantic versioning but also unique and represent a version that is newer than any previously released. -1. **Commit Convention:** While not mandatory, it is beneficial to ensure an informative changelog by following the [Commit Convention](commit.md#commit-message-pattern) so that corresponding commit messages can be included in the changelog. -1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the [project configuration](proj.md#project-configuration). +1. **Commit Convention:** While not mandatory, it is beneficial to ensure an informative changelog by following the [Commit Convention](../development/commit.md#commit-message-pattern) so that corresponding commit messages can be included in the changelog. +1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the [project configuration](./config.md). diff --git a/template/docs/management/update.md.jinja b/template/docs/management/update.md.jinja new file mode 100644 index 00000000..535ebf2f --- /dev/null +++ b/template/docs/management/update.md.jinja @@ -0,0 +1,22 @@ +# Template Update + +Thanks to the update mechanism provided natively by `copier`, when a new version of the template is released, you can easily update the project. Just run the following command under the root directory: + +```bash +copier update +``` + +```{note} +The `-A/--skip-answered` flag can be used to skip questions that have already been answered. +``` + +In most cases, `copier` will manage updates seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. + +```{tip} +To minimize potential conflicts, there are several suggestions to follow: +1. Avoid modifying the auto-generated files unless absolutely necessary. +1. For template-related changes, consider proposing an issue or change request directly to the template repository. +1. For project-specific changes, adopt an inheritance or extension approach to minimize the changes to auto-generated contents. +``` + +For more details, please refer to `copier update --help` and [the official documentation](https://copier.readthedocs.io/en/stable/updating/). From 472d56c4f2a0bf7c37b46b7909b9413da2ce51fe Mon Sep 17 00:00:00 2001 From: "Xuan (Sean) Hu" Date: Fri, 17 May 2024 09:20:38 +0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: msclock Signed-off-by: Xuan (Sean) Hu --- docs/advanced/partial-dev-env.md | 22 ++++++++++---------- docs/development/cleanup-dev-env.md | 2 +- template/docs/advanced/partial-dev-env.md | 22 ++++++++++---------- template/docs/development/cleanup-dev-env.md | 2 +- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/advanced/partial-dev-env.md b/docs/advanced/partial-dev-env.md index 467b14fb..c325eb06 100644 --- a/docs/advanced/partial-dev-env.md +++ b/docs/advanced/partial-dev-env.md @@ -1,10 +1,10 @@ # Partially Set Up Development Environment -In certain cases, it is unnecessary to install all dependencies as well as the pre-commit hook. For example, speed up the setup process in CI/CD. +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 only with necessary dependencies, useful for scenarios like deployment. +Install the project in editable mode with only the necessary dependencies, which is useful for scenarios like deployment. ```bash make install @@ -12,8 +12,8 @@ make install ## Documentation generation -Install the project in editable mode with `doc` related dependencies, -recommended for scenarios like documentation generation CI/CD process. +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 @@ -21,8 +21,8 @@ make dev-doc ## Lint check -Install the project in editable mode with `lint` related dependencies, -recommended for scenarios like lint CI/CD process. +Install the project in editable mode with dependencies related to `lint`, +recommended for scenarios like the lint CI/CD process. ```bash make dev-lint @@ -30,8 +30,8 @@ make dev-lint ## Package build -Install the project in editable mode with `package` related dependencies, -recommended for scenarios like package CI/CD process. +Install the project in editable mode with dependencies related to `package`, +recommended for scenarios like the package CI/CD process. ```bash make dev-package @@ -39,8 +39,8 @@ make dev-package ## Testing -Install the project in editable mode with `test` related dependencies, -recommended for scenarios like test CI/CD process. +Install the project in editable mode with dependencies related to `test`, +recommended for scenarios like the test CI/CD process. ```bash make dev-test @@ -48,7 +48,7 @@ make dev-test ## Combination -For example, to install dependencies for `doc` and `lint`, we can use the following command. +To install dependencies for `doc `and `lint`, use the following command: ```bash make dev-doc,lint diff --git a/docs/development/cleanup-dev-env.md b/docs/development/cleanup-dev-env.md index d4057a9a..fe63f296 100644 --- a/docs/development/cleanup-dev-env.md +++ b/docs/development/cleanup-dev-env.md @@ -1,6 +1,6 @@ # 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. +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 diff --git a/template/docs/advanced/partial-dev-env.md b/template/docs/advanced/partial-dev-env.md index 467b14fb..c325eb06 100644 --- a/template/docs/advanced/partial-dev-env.md +++ b/template/docs/advanced/partial-dev-env.md @@ -1,10 +1,10 @@ # Partially Set Up Development Environment -In certain cases, it is unnecessary to install all dependencies as well as the pre-commit hook. For example, speed up the setup process in CI/CD. +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 only with necessary dependencies, useful for scenarios like deployment. +Install the project in editable mode with only the necessary dependencies, which is useful for scenarios like deployment. ```bash make install @@ -12,8 +12,8 @@ make install ## Documentation generation -Install the project in editable mode with `doc` related dependencies, -recommended for scenarios like documentation generation CI/CD process. +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 @@ -21,8 +21,8 @@ make dev-doc ## Lint check -Install the project in editable mode with `lint` related dependencies, -recommended for scenarios like lint CI/CD process. +Install the project in editable mode with dependencies related to `lint`, +recommended for scenarios like the lint CI/CD process. ```bash make dev-lint @@ -30,8 +30,8 @@ make dev-lint ## Package build -Install the project in editable mode with `package` related dependencies, -recommended for scenarios like package CI/CD process. +Install the project in editable mode with dependencies related to `package`, +recommended for scenarios like the package CI/CD process. ```bash make dev-package @@ -39,8 +39,8 @@ make dev-package ## Testing -Install the project in editable mode with `test` related dependencies, -recommended for scenarios like test CI/CD process. +Install the project in editable mode with dependencies related to `test`, +recommended for scenarios like the test CI/CD process. ```bash make dev-test @@ -48,7 +48,7 @@ make dev-test ## Combination -For example, to install dependencies for `doc` and `lint`, we can use the following command. +To install dependencies for `doc `and `lint`, use the following command: ```bash make dev-doc,lint diff --git a/template/docs/development/cleanup-dev-env.md b/template/docs/development/cleanup-dev-env.md index d4057a9a..fe63f296 100644 --- a/template/docs/development/cleanup-dev-env.md +++ b/template/docs/development/cleanup-dev-env.md @@ -1,6 +1,6 @@ # 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. +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 From ab5a27bfed70a4b447f303ecde04a1427f69657a Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Fri, 17 May 2024 09:21:51 +0800 Subject: [PATCH 4/4] minor --- docs/advanced/partial-dev-env.md | 2 +- template/docs/advanced/partial-dev-env.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/partial-dev-env.md b/docs/advanced/partial-dev-env.md index c325eb06..a08de2b7 100644 --- a/docs/advanced/partial-dev-env.md +++ b/docs/advanced/partial-dev-env.md @@ -48,7 +48,7 @@ make dev-test ## Combination -To install dependencies for `doc `and `lint`, use the following command: +To install dependencies for `doc` and `lint`, use the following command: ```bash make dev-doc,lint diff --git a/template/docs/advanced/partial-dev-env.md b/template/docs/advanced/partial-dev-env.md index c325eb06..a08de2b7 100644 --- a/template/docs/advanced/partial-dev-env.md +++ b/template/docs/advanced/partial-dev-env.md @@ -48,7 +48,7 @@ make dev-test ## Combination -To install dependencies for `doc `and `lint`, use the following command: +To install dependencies for `doc` and `lint`, use the following command: ```bash make dev-doc,lint