Switch to note admonition in readme (#1216)

* Switch to note admonition in readme * docs: use GFM syntax for admonitions Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> --------- Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>
pypa · Jan 18, 2024 · f52b8d4 · f52b8d4
1 parent ddf8a1c
commit f52b8d4
Show file tree

Hide file tree

Showing 5 changed files with 47 additions and 34 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -126,19 +126,21 @@ To run unit tests in Python3.12, you can run
 nox -s tests-3.12
 ```
 
-!!! tip You can run a specific unit test by passing arguments to pytest, the test runner pipx uses:
-
-    ```
-    nox -s tests-3.8 -- -k EXPRESSION
-    ```
-
-    `EXPRESSION` can be a test name, such as
-
-    ```
-    nox -s tests-3.8 -- -k test_uninstall
-    ```
-
-    Coverage errors can usually be ignored when only running a subset of tests.
+> [!TIP]
+>
+> You can run a specific unit test by passing arguments to pytest, the test runner pipx uses:
+>
+> ```
+> nox -s tests-3.8 -- -k EXPRESSION
+> ```
+>
+> `EXPRESSION` can be a test name, such as
+>
+> ```
+> nox -s tests-3.8 -- -k test_uninstall
+> ```
+>
+> Coverage errors can usually be ignored when only running a subset of tests.
 
 ### Running Unit Tests Offline
 

diff --git a/README.md b/README.md
@@ -27,7 +27,9 @@ _For comparison to other tools including pipsi, see
 
 ## Install pipx
 
-> [!NOTE] It is not recommended to install `pipx` via `pipx`. If you'd like to do this anyway, take a look at the
+> [!WARNING]
+>
+> It is not recommended to install `pipx` via `pipx`. If you'd like to do this anyway, take a look at the
 > [`pipx-in-pipx`](https://github.com/mattsb42-meta/pipx-in-pipx) project and read about the limitations there.
 
 ### On macOS

diff --git a/docs/installation.md b/docs/installation.md
@@ -68,10 +68,10 @@ you did not get the warning):
 This will add both the above mentioned path and the `%USERPROFILE%\.local\bin` folder to your search path. Restart your
 terminal session and verify `pipx` does run.
 
-!!! warning
-
-    It is not recommended to install `pipx` via `pipx`. If you'd like to do this anyway, take a look at the
-    [`pipx-in-pipx`](https://github.com/mattsb42-meta/pipx-in-pipx) project and read about the limitations there.
+> [!WARNING]
+>
+> It is not recommended to install `pipx` via `pipx`. If you'd like to do this anyway, take a look at the
+> [`pipx-in-pipx`](https://github.com/mattsb42-meta/pipx-in-pipx) project and read about the limitations there.
 
 ### Using pipx without installing (via zipapp)
 
@@ -123,20 +123,21 @@ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin PIPX_MAN_DIR=/usr/local/sha
 # Example: $ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin PIPX_MAN_DIR=/usr/local/share/man pipx install cowsay
 ```
 
-!!! note
-
-    After version 1.2.0, the default pipx paths have been moved from `~/.local/pipx` to specific user data directories on each platform using [platformdirs](https://pypi.org/project/platformdirs/) library
-
-    | Old Path               | New Path                                   |
-    | ---------------------- | ------------------------------------------ |
-    | `~/.local/pipx/.trash` | `platformdirs.user_data_dir()/pipx/trash`  |
-    | `~/.local/pipx/shared` | `platformdirs.user_data_dir()/pipx/shared` |
-    | `~/.local/pipx/venvs`  | `platformdirs.user_data_dir()/pipx/venv`   |
-    | `~/.local/pipx/.cache` | `platformdirs.user_cache_dir()/pipx`       |
-    | `~/.local/pipx/logs`   | `platformdirs.user_log_dir()/pipx/log`     |
-
-    `user_data_dir()`, `user_cache_dir()` and `user_log_dir()` resolve to appropriate platform-specific user data, cache and log directories.
-    See the [platformdirs documentation](https://platformdirs.readthedocs.io/en/latest/api.html#platforms) for details.
+> [!NOTE]
+>
+> After version 1.2.0, the default pipx paths have been moved from `~/.local/pipx` to specific user data directories on
+> each platform using [platformdirs](https://pypi.org/project/platformdirs/) library
+>
+> | Old Path               | New Path                                   |
+> | ---------------------- | ------------------------------------------ |
+> | `~/.local/pipx/.trash` | `platformdirs.user_data_dir()/pipx/trash`  |
+> | `~/.local/pipx/shared` | `platformdirs.user_data_dir()/pipx/shared` |
+> | `~/.local/pipx/venvs`  | `platformdirs.user_data_dir()/pipx/venv`   |
+> | `~/.local/pipx/.cache` | `platformdirs.user_cache_dir()/pipx`       |
+> | `~/.local/pipx/logs`   | `platformdirs.user_log_dir()/pipx/log`     |
+>
+> `user_data_dir()`, `user_cache_dir()` and `user_log_dir()` resolve to appropriate platform-specific user data, cache and log directories.
+> See the [platformdirs documentation](https://platformdirs.readthedocs.io/en/latest/api.html#platforms) for details.
 
 ## Upgrade pipx
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -39,7 +39,7 @@ nav:
   - Changelog: "changelog.md"
 
 markdown_extensions:
-  - admonition  #  note blocks, warning blocks -- https://github.com/mkdocs/mkdocs/issues/1659
+  - markdown_gfm_admonition  # GitHub's admonition (alert) syntax
 
 plugins:
   - search:

diff --git a/noxfile.py b/noxfile.py
@@ -7,7 +7,15 @@
 
 PYTHON_ALL_VERSIONS = ["3.12", "3.11", "3.10", "3.9", "3.8"]
 PYTHON_DEFAULT_VERSION = "3.12"
-DOC_DEPENDENCIES = ["jinja2", "mkdocs", "mkdocs-material", "mkdocs-gen-files", "mkdocs-macros-plugin", "towncrier"]
+DOC_DEPENDENCIES = [
+    "jinja2",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocs-gen-files",
+    "mkdocs-macros-plugin",
+    "towncrier",
+    "markdown-gfm-admonition",
+]
 MAN_DEPENDENCIES = ["argparse-manpage[setuptools]"]
 TEST_DEPENDENCIES = ["pytest", "pypiserver[passlib]", 'setuptools; python_version>="3.12"', "pytest-cov"]
 # Packages whose dependencies need an intact system PATH to compile