From 3042979d8317c2c809815648fdbe202a609d1fa7 Mon Sep 17 00:00:00 2001 From: "Xuan (Sean) Hu" Date: Tue, 24 Oct 2023 13:17:53 +0800 Subject: [PATCH] docs: No code fence and the official myst VSCode extension. (#213) --- .vscode/extensions.json | 2 +- docs/conf.py | 7 ------- docs/dev/env.md | 18 ++++++++---------- template/.vscode/extensions.json | 2 +- template/docs/conf.py.jinja | 7 ------- template/docs/dev/env.md | 18 ++++++++---------- 6 files changed, 18 insertions(+), 36 deletions(-) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 3eeefedd..986cc4c8 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,13 +1,13 @@ { "recommendations": [ "DavidAnson.vscode-markdownlint", + "ExecutableBookProject.myst-highlight", "PascalReitermann93.vscode-yaml-sort", "charliermarsh.ruff", "ms-python.black-formatter", "ms-python.mypy-type-checker", "ms-python.python", "richie5um2.vscode-sort-json", - "shd101wyy.markdown-preview-enhanced", "streetsidesoftware.code-spell-checker", "trond-snekvik.simple-rst" ] diff --git a/docs/conf.py b/docs/conf.py index a6fd852d..2e883ea0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,10 +52,3 @@ # https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html autodoc_pydantic_settings_show_json = False - -# -- Options for myst-parser ------------------------------------------------- -# https://myst-parser.readthedocs.io/en/latest/configuration.html - -myst_enable_extensions = [ - "colon_fence", -] diff --git a/docs/dev/env.md b/docs/dev/env.md index bbdb970a..3104abf5 100644 --- a/docs/dev/env.md +++ b/docs/dev/env.md @@ -4,9 +4,9 @@ After generating the project via `copier`, several necessary tools can be installed with the following commands. -:::{note} +```{note} Using `pipx` for management is recommended and you can find pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). -::: +``` ```bash # Pipenv: Virtual environment and package manager for Python. @@ -17,9 +17,9 @@ pipx install pre-commit ## Environment Setup -:::{note} +```{note} A universal `Makefile` is located at the root directory of the repo, and all `make` related commands are supposed to run there. -::: +``` There is an all-in-one command to setup environment for daily development. @@ -57,9 +57,9 @@ make deepclean With this command, the repo will be as if it has been re-cloned. It is useful if we want to start almost from scratch. -:::{caution} +```{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 @@ -115,13 +115,11 @@ recommended for scenarios like test CI/CD process. make dev-test ``` -:::{admonition} Install a combination of the optional dependencies +````{admonition} Install a combination of the optional dependencies :class: tip, dropdown - For example, to install requirements for `docs` and `lint`, we can use the following command. ```bash make dev-docs,lint ``` - -::: +```` diff --git a/template/.vscode/extensions.json b/template/.vscode/extensions.json index 3eeefedd..986cc4c8 100644 --- a/template/.vscode/extensions.json +++ b/template/.vscode/extensions.json @@ -1,13 +1,13 @@ { "recommendations": [ "DavidAnson.vscode-markdownlint", + "ExecutableBookProject.myst-highlight", "PascalReitermann93.vscode-yaml-sort", "charliermarsh.ruff", "ms-python.black-formatter", "ms-python.mypy-type-checker", "ms-python.python", "richie5um2.vscode-sort-json", - "shd101wyy.markdown-preview-enhanced", "streetsidesoftware.code-spell-checker", "trond-snekvik.simple-rst" ] diff --git a/template/docs/conf.py.jinja b/template/docs/conf.py.jinja index 298ccd67..c901a742 100644 --- a/template/docs/conf.py.jinja +++ b/template/docs/conf.py.jinja @@ -52,10 +52,3 @@ autodoc_default_options = { # https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html autodoc_pydantic_settings_show_json = False - -# -- Options for myst-parser ------------------------------------------------- -# https://myst-parser.readthedocs.io/en/latest/configuration.html - -myst_enable_extensions = [ - "colon_fence", -] diff --git a/template/docs/dev/env.md b/template/docs/dev/env.md index bbdb970a..3104abf5 100644 --- a/template/docs/dev/env.md +++ b/template/docs/dev/env.md @@ -4,9 +4,9 @@ After generating the project via `copier`, several necessary tools can be installed with the following commands. -:::{note} +```{note} Using `pipx` for management is recommended and you can find pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). -::: +``` ```bash # Pipenv: Virtual environment and package manager for Python. @@ -17,9 +17,9 @@ pipx install pre-commit ## Environment Setup -:::{note} +```{note} A universal `Makefile` is located at the root directory of the repo, and all `make` related commands are supposed to run there. -::: +``` There is an all-in-one command to setup environment for daily development. @@ -57,9 +57,9 @@ make deepclean With this command, the repo will be as if it has been re-cloned. It is useful if we want to start almost from scratch. -:::{caution} +```{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 @@ -115,13 +115,11 @@ recommended for scenarios like test CI/CD process. make dev-test ``` -:::{admonition} Install a combination of the optional dependencies +````{admonition} Install a combination of the optional dependencies :class: tip, dropdown - For example, to install requirements for `docs` and `lint`, we can use the following command. ```bash make dev-docs,lint ``` - -::: +````