docs: No code fence and the official myst VSCode extension. (#213)

serious-scaffold · Oct 24, 2023 · 3042979 · 3042979
1 parent af3d5d8
commit 3042979
Show file tree

Hide file tree

Showing 6 changed files with 18 additions and 36 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
 ```
-
-:::
+````