Add install_from_adt macro (#117)

.config/constraints.txt

@@ -33,6 +33,7 @@ mkdocs==1.5.3
 mkdocs-autorefs==1.0.1
 mkdocs-gen-files==0.5.0
 mkdocs-htmlproofer-plugin==1.2.0
+mkdocs-macros-plugin==1.0.5
 mkdocs-material==9.5.13
 mkdocs-material-extensions==1.3.1
 mkdocs-minify-plugin==0.8.0
@@ -56,6 +57,7 @@ regex==2023.12.25
 requests==2.31.0
 six==1.16.0
 soupsieve==2.5
+termcolor==2.4.0
 text-unidecode==1.3
 tinycss2==1.2.1
 urllib3==2.2.1

.config/dictionary.txt

@@ -19,6 +19,7 @@ commitlint
 devel
 dists
 docstrings
+endraw
 fontawesome
 htmlproofer
 inlinehilite

.config/requirements.in

@@ -4,6 +4,7 @@ markdown-exec>=1.3.0
 markdown-include>=0.8.1
 mkdocs-gen-files>=0.4.0
 mkdocs-htmlproofer-plugin>=0.10.2
+mkdocs-macros-plugin
 mkdocs-material-extensions>=1.1.1
 mkdocs-material>=9.0.13
 mkdocs-minify-plugin>=0.6.2

.pre-commit-config.yaml

@@ -26,14 +26,14 @@ repos:
           - prettier-plugin-toml
           - prettier-plugin-sort-json
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v8.3.0
+    rev: v8.6.0
     hooks:
       - id: cspell
         # entry: codespell --relative
         args: [--relative, --no-progress, --no-summary]
         name: Spell check with cspell
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.27.4
+    rev: 0.28.0
     hooks:
       - id: check-github-workflows
   - repo: https://github.com/pre-commit/pre-commit-hooks.git
@@ -58,7 +58,7 @@ repos:
         additional_dependencies:
           - tomli
   - repo: https://github.com/adrienverge/yamllint.git
-    rev: v1.33.0
+    rev: v1.35.1
     hooks:
       - id: yamllint
         files: \.(yaml|yml)$
@@ -72,44 +72,32 @@ repos:
           # https://github.com/pre-commit/mirrors-isort/issues/9#issuecomment-624404082
           - --filter-files
   - repo: https://github.com/psf/black
-    rev: 24.1.1
+    rev: 24.3.0
     hooks:
       - id: black
         language_version: python3
-  - repo: https://github.com/pycqa/flake8.git
-    rev: 7.0.0
-    hooks:
-      - id: flake8
-        language_version: python3
-        additional_dependencies:
-          - flake8-2020>=1.6.0
-          # - flake8-black>=0.1.1
-          - flake8-docstrings>=1.5.0
-          - flake8-print>=5.0
-          - flake8-pytest-style>=1.2.2
-          - flake8-future-annotations>=0.0.3
   - repo: https://github.com/asottile/pyupgrade
     # keep it after flake8
-    rev: v3.15.0
+    rev: v3.15.2
     hooks:
       - id: pyupgrade
         args: ["--py39-plus"]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
+    rev: v1.9.0
     hooks:
       - id: mypy
         # empty args needed in order to match mypy cli behavior
         args: []
-        additional_dependencies: []
+        additional_dependencies: ["mkdocs-macros-plugin"]
   - repo: https://github.com/pycqa/pylint
-    rev: v3.0.3
+    rev: v3.1.0
     hooks:
       - id: pylint
         args:
           - --output-format=colorized
-        additional_dependencies: []
+        additional_dependencies: ["mkdocs-macros-plugin"]
   - repo: https://github.com/jazzband/pip-tools
-    rev: 7.3.0
+    rev: 7.4.1
     hooks:
       - id: pip-compile
         name: lock

docs/README.md

@@ -13,7 +13,6 @@ Some of the projects that use this theme are:
 
 - [ansible-compat](https://ansible.readthedocs.io/projects/compat/)
 - [ansible-dev-tools](https://ansible.readthedocs.io/projects/dev-tools/)
-- [ansible-language-server](https://ansible.readthedocs.io/projects/language-server/)
 - [ansible-lint](https://ansible.readthedocs.io/projects/lint/)
 - [ansible-navigator](https://ansible.readthedocs.io/projects/navigator/)
 - [molecule](https://ansible.readthedocs.io/projects/molecule/)

docs/macros.md

@@ -0,0 +1,30 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# Enabling mkdocs-ansible macros
+
+In order to activate the macros inside your documentation project you need to
+add:
+
+```yaml
+# mkdocs.yml
+plugins:
+  - macros:
+      modules: [mkdocs-ansible:mkdocs_ansible]
+```
+
+# Using install_from_adt macro
+
+Inside markdown documentation include a section like below, the expanded
+result can be seen after the example.
+
+```markdown
+{% raw %}
+{{ install_from_adt("ansible-navigator") }}
+{% endraw %}
+```
+
+{{ install_from_adt("ansible-navigator") }}

linkcheckerrc

@@ -4,6 +4,9 @@ checkextern=1
 ignore=
   xml.gz$
   404.html
+  https://github.com/ansible/mkdocs-ansible/(blob|raw)/main/docs/.*\.md
+  https://ansible.readthedocs.io/projects/mkdocs-ansible/.*
+# https://github.com/linkchecker/linkchecker/discussions/811
 # https://github.com/squidfunk/mkdocs-material/pull/6386
 ignorewarnings=http-redirected
 

mkdocs.yml

@@ -45,9 +45,12 @@ theme:
 
 nav:
   - Home: README.md
+  - Macros: macros.md
 
 # Plugins
 plugins:
+  - macros:
+      modules: [mkdocs-ansible:mkdocs_ansible]
   - material/social
   - material/search:
       separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'

pyproject.toml

@@ -46,6 +46,11 @@ python_version = "3.10"
 warn_unused_configs = true
 exclude = ['build']
 
+# https://github.com/fralau/mkdocs-macros-plugin/issues/219
+[[tool.mypy.overrides]]
+module = ["mkdocs_macros.plugin"]
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = ["mkdocs_ansible._version"]
 warn_unused_ignores = false

src/mkdocs_ansible/__init__.py

@@ -1,9 +1,40 @@
 """mkdocs-ansible theme."""
 
+from __future__ import annotations
+
 try:
     from ._version import version as __version__  # type: ignore
 
 except ImportError:  # pragma: no cover
     __version__ = "0.1.dev1"
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mkdocs_macros.plugin import MacrosPlugin
 
 __all__ = ("__version__",)
+
+
+def install_from_adt(name: str) -> str:
+    """install_from_adt macro."""
+    result = f"""!!! Recommendation
+
+    The **recommended** approach to install `{name}` is using the
+    `ansible-dev-tools` package.
+    [Ansible Development Tools (ADT)](https://ansible.readthedocs.io/projects/dev-tools/)
+    aims to streamline the setup and usage of several tools needed in order to
+    create [Ansible](https://www.ansible.com) content. ADT combines critical Ansible
+    development packages into a unified Python package.
+
+    ```bash
+    # This also installs ansible-core if it is not already installed
+    pip3 install ansible-dev-tools
+    ```
+    """
+    return result
+
+
+def define_env(env: MacrosPlugin) -> None:
+    """Declare environment for jinja2 templates for markdown."""
+    for fn in [install_from_adt]:
+        env.macro(fn)