Use proper callouts

hynek · Jan 14, 2024 · a8b06fb · a8b06fb
1 parent 34e4ea1
commit a8b06fb
Show file tree

Hide file tree

Showing 7 changed files with 51 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -31,7 +31,7 @@ The fastest way to get started is installing *doc2dash* from our [Homebrew tap](
 $ brew install hynek/tap/doc2dash
 ```
 
-> **Note**
+> [!NOTE]
 > If you can’t – or won’t – use [Homebrew](https://brew.sh), check out our [installation instructions](https://doc2dash.hynek.me/en/latest/installation/) for alternatives.
 
 Then point *doc2dash* at a directory containing **built** [*intersphinx*-compatible](https://doc2dash.hynek.me/en/stable/formats/) documentation:

diff --git a/docs/formats.md b/docs/formats.md
@@ -15,10 +15,9 @@ The most common documentation formats that support *intersphinx* are:
 
 If you find a documentation format that supports *intersphinx* but yields poor results from *doc2dash*, please [let us know](https://github.com/hynek/doc2dash/issues).
 
-!!! Warning
-
-    Do **not** attempt to run *doc2dash* over pre-built HTML documentation downloaded from [*Read The Docs*](https://readthedocs.org).
-    Those downloads aren't direct equivalents of the actual, pristine builds and indexing will not work.
+> [!WARNING]
+> Do **not** attempt to run *doc2dash* over pre-built HTML documentation downloaded from [*Read The Docs*](https://readthedocs.org).
+> Those downloads aren't direct equivalents of the actual, pristine builds and indexing will not work.
 
 [^pydoctor]:
     Dedicated support for *pydoctor* has been removed after it became *intersphinx*-compatible.

diff --git a/docs/installation.md b/docs/installation.md
@@ -15,12 +15,12 @@ We try to provide as many pre-built bottles as possible.
 
 As of version 3.0, the [releases](https://github.com/hynek/doc2dash/releases) come with **pre-compiled binaries** for Linux, macOS, and Windows on Intel x64 that you can simply download and run *without* any other dependencies.
 
-!!! Warning
-    On macOS, you may get a warning about an unsigned binary.
-    To get rid of that you have two options:
-
-    1. Run `xattr -d com.apple.quarantine ~/Downloads/doc2dash/doc2dash` after unpacking the downloaded archive inside your Downloads folder.
-    1. Open the binary in Finder once using right-click.
+> [!WARNING]
+> On macOS, you may get a warning about an unsigned binary.
+> To get rid of that you have two options:
+>
+> 1. Run `xattr -d com.apple.quarantine ~/Downloads/doc2dash/doc2dash` after unpacking the downloaded archive inside your Downloads folder.
+> 1. Open the binary in Finder once using right-click.
 
 
 ## PyPI

diff --git a/docs/submit.md b/docs/submit.md
@@ -1,7 +1,7 @@
 # Building and Submitting Docsets to Dash.app
 
-!!! Note
-    This how-to is extracted from [*How I'm a Productive Programmer With a Memory of a Fruit Fly*](https://hynek.me/articles/productive-fruit-fly-programmer/).
+> [!NOTE]
+> This how-to is extracted from [*How I'm a Productive Programmer With a Memory of a Fruit Fly*](https://hynek.me/articles/productive-fruit-fly-programmer/).
 
 The goal of this how-to is to teach you how to convert *intersphinx*-compatible documentation to a docset and how to submit it to Dash's [*user-generated docset registry*](https://github.com/Kapeli/Dash-User-Contributions), such that others don't have to duplicate your work.
 
@@ -29,11 +29,11 @@ Once you've managed to install all dependencies, it's usually just a matter of `
 
 After figuring this out, you should have a directory called `_build/html` for Sphinx or `site` for MkDocs.
 
-!!! Note
-    Please note with MkDocs that if the project doesn't use the [*mkdocstrings*](https://mkdocstrings.github.io) extension -- which, alas, is virtually all of the popular ones at the moment -- there won't be an `objects.inv` file and therefore no API data to be consumed.
-
-    I hope that more MkDocs-based projects add support for *mkdocstrings* in the future!
-    As with Sphinx, it's language-agnostic.
+> [!NOTE]
+> Please note with MkDocs that if the project doesn't use the [*mkdocstrings*](https://mkdocstrings.github.io) extension -- which, alas, is virtually all of the popular ones at the moment -- there won't be an `objects.inv` file and therefore no API data to be consumed.
+>
+> I hope that more MkDocs-based projects add support for *mkdocstrings* in the future!
+> As with Sphinx, it's language-agnostic.
 
 
 ## Converting
@@ -143,11 +143,11 @@ Since I want to create a new version of the docsets for every new release, the c
 
 For local testing, I'll take advantage of *doc2dash* being a Python project and use a [*tox*](https://tox.wiki/) environment that reuses the dependencies that I use when testing documentation itself.
 
-!!! Note
-    *tox* is a combination of Make and a virtual environment manager based on the `ini` file format.
-    Its original purpose was testing Python software over multiple Python versions but has grown a lot more powerful.
-
-    The big upsides over a `Makefile` are that it's more portable and has support for Python packaging built-in (which is necessary for building the documentation anyways).
+> [!NOTE]
+> *tox* is a combination of Make and a virtual environment manager based on the `ini` file format.
+> Its original purpose was testing Python software over multiple Python versions but has grown a lot more powerful.
+>
+> The big upsides over a `Makefile` are that it's more portable and has support for Python packaging built-in (which is necessary for building the documentation anyways).
 
 The environment installs `structlog[docs]` -- meaning: the package with optional `docs` dependencies, plus *doc2dash*.
 Then it runs `commands` in order:

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -76,6 +76,7 @@ markdown_extensions:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 plugins:
+  - callouts
   - include-markdown
   - mkdocstrings:
       handlers:

diff --git a/pyproject.toml b/pyproject.toml
@@ -11,26 +11,27 @@ authors = [{ name = "Hynek Schlawack", email = "hs@ox.cx" }]
 requires-python = ">=3.8"
 license = "MIT"
 classifiers = [
-    "Development Status :: 5 - Production/Stable",
-    "Environment :: Console",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Topic :: Software Development :: Documentation",
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Documentation",
 ]
 dependencies = ["attrs>=21.3", "beautifulsoup4", "click>8", "rich"]
 
 [project.optional-dependencies]
 tests = ["coverage[toml]", "pytest"]
 docs = [
-    "mkdocs",
-    "mkdocs-material",
-    "mkdocs-include-markdown-plugin",
-    "mkdocs-click",
-    "mkdocstrings[python]",
+  "mkdocs",
+  "mkdocs-material",
+  "mkdocs-include-markdown-plugin",
+  "mkdocs-click",
+  "mkdocs-callouts",
+  "mkdocstrings[python]",
 ]
 typing = ["mypy", "types-urllib3"]
 dev = ["doc2dash[tests,typing]"]
@@ -71,14 +72,14 @@ source = ["src", ".nox/tests-*/**/site-packages"]
 show_missing = true
 skip_covered = true
 exclude_lines = [
-    "pragma: no cover",
-    "if TYPE_CHECKING:",
-    "raise NotImplementedError",
-    # typing-related code
-    "^if (False|TYPE_CHECKING):",
-    ": \\.\\.\\.$",
-    "^ +\\.\\.\\.$",
-    "-> ['\"]?NoReturn['\"]?:",
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+  # typing-related code
+  "^if (False|TYPE_CHECKING):",
+  ": \\.\\.\\.$",
+  "^ +\\.\\.\\.$",
+  "-> ['\"]?NoReturn['\"]?:",
 ]
 
 

diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -242,13 +242,18 @@ mkdocs==1.5.3 \
     # via
     #   doc2dash (pyproject.toml)
     #   mkdocs-autorefs
+    #   mkdocs-callouts
     #   mkdocs-include-markdown-plugin
     #   mkdocs-material
     #   mkdocstrings
 mkdocs-autorefs==0.5.0 \
     --hash=sha256:7930fcb8ac1249f10e683967aeaddc0af49d90702af111a5e390e8b20b3d97ff \
     --hash=sha256:9a5054a94c08d28855cfab967ada10ed5be76e2bfad642302a610b252c3274c0
     # via mkdocstrings
+mkdocs-callouts==1.10.0 \
+    --hash=sha256:0fb0472d9f9453ece20a7ed85f4d2dedb91b61bd64a28eea863966349826d31f \
+    --hash=sha256:cf29b2d36ac994c1999ebc50ac8a3edefc7f7e28b88a3fbf3a8676f9d6822c89
+    # via doc2dash (pyproject.toml)
 mkdocs-click==0.8.1 \
     --hash=sha256:0a88cce04870c5d70ff63138e2418219c3c4119cc928a59c66b76eb5214edba6 \
     --hash=sha256:a100ff938be63911f86465a1c21d29a669a7c51932b700fdb3daa90d13b61ee4