Merge pull request #452 from numpy/docs/markdown-extensions

📝 spice up the docs using markdown extensions

Author: jorenham

docs/user_guide/differences.md

@@ -44,28 +44,92 @@ But the now concrete scalar types will no longer accept *any* `#!py floating[T]`
 
 Type parameters can instead use an abstract scalar type as an upper bound. So instead of
 
+/// tab | Python 3.10 and above
+
 ```py
-def f[T: npt.NBitBase](x: np.floating[T]) -> np.floating[T]: ...
+import numpy as np
+import numpy.typing as npt
+from typing import TypeVar
+
+NT = TypeVar("NT", bound=npt.NBitBase)
+
+def f(x: np.floating[NT]) -> np.floating[NT]: ...
+```
+
+///
+/// tab | Python 3.12 and above
+    select: True
+
+```py
+import numpy as np
+import numpy.typing as npt
+
+def f[NT: npt.NBitBase](x: np.floating[NT]) -> np.floating[NT]: ...
 ```
 
+///
+
 you can write
 
+/// tab | Python 3.10 and above
+
 ```py
+import numpy as np
+from typing import TypeVar
+
+FloatT = TypeVar("FloatT", bound=np.floating)
+
+def f(x: FloatT) -> FloatT: ...
+```
+
+///
+/// tab | Python 3.12 and above
+    select: True
+
+```py
+import numpy as np
+
 def f[FloatT: np.floating](x: FloatT) -> FloatT: ...
 ```
 
+///
+
 As you can see, this also makes the code more readable.
 
 But what if that isn't possible? For instance, you might have the following function:
 
+/// tab | Python 3.10 and above
+
 ```py
-def f[T: npt.NBitBase](x: np.complexfloating[T]) -> np.floating[T]: ...
+import numpy as np
+import numpy.typing as npt
+from typing import TypeVar
+
+NT = TypeVar("NT", bound=npt.NBitBase)
+
+def f(x: np.complexfloating[NT]) -> np.floating[NT]: ...
 ```
 
+///
+/// tab | Python 3.12 and above
+    select: True
+
+```py
+import numpy as np
+import numpy.typing as npt
+
+def f[NT: npt.NBitBase](x: np.complexfloating[NT]) -> np.floating[NT]: ...
+```
+
+///
+
 In that case, you can rewrite it by using
 [`#!py typing.overload`](https://typing.python.org/en/latest/spec/overload.html):
 
 ```py
+import numpy as np
+from typing import overload
+
 @overload
 def f(x: np.complex64) -> np.float32: ...
 @overload

mkdocs.yml

@@ -44,24 +44,33 @@ plugins:
             show_source: false
             show_signature_annotations: true
 
-  # https://squidfunk.github.io/mkdocs-material/plugins/search/
-  - search
-
   # https://squidfunk.github.io/mkdocs-material/plugins/privacy/
   - privacy:
       enabled: !ENV [CI, false]
 
+  # https://squidfunk.github.io/mkdocs-material/plugins/search/
+  - search
+
 markdown_extensions:
   # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/
   - abbr
-  - admonition
   - attr_list
   - def_list
   - footnotes
   - md_in_html
   - toc:
       permalink: "🔗"
 
+  # https://github.com/oprypin/markdown-callouts
+  - callouts
+
+  # https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
+  - pymdownx.betterem:
+      smart_enable: asterisk
+
+  - pymdownx.blocks.tab:
+      alternate_style: true
+
   # https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
@@ -82,6 +91,24 @@ markdown_extensions:
       user: numpy
       repo: numtype
 
+  # https://facelessuser.github.io/pymdown-extensions/extensions/saneheaders/
+  - pymdownx.saneheaders
+
+extra:
+  analytics:
+    provider: google
+    property: G-JYJJ7JYLG1
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+
+extra_css:
+  - style/theme.css
+
 theme:
   name: material
   favicon: img/favicon.ico
@@ -126,19 +153,4 @@ theme:
         icon: fontawesome/regular/sun
         name: Switch to system preference
 
-extra_css:
-  - style/theme.css
-
-extra:
-  analytics:
-    provider: google
-    property: G-JYJJ7JYLG1
-  consent:
-    title: Cookie consent
-    description: >-
-      We use cookies to recognize your repeated visits and preferences, as well
-      as to measure the effectiveness of our documentation and whether users
-      find what they're searching for. With your consent, you're helping us to
-      make our documentation better.
-
 copyright: Copyright ©, 2025 NumPy Developers.

pyproject.toml

@@ -81,6 +81,7 @@ typecheck = [
 docs = [
     "mkdocs-material>=9.6.10",
     "mkdocs-awesome-nav>=3.1.0",
+    "markdown-callouts>=0.4.0",
     "mkdocs-include-markdown-plugin>=7.1.5",
     "mkdocs-minify-plugin>=0.8.0",
     "mkdocstrings[python]>=0.29.1",