diff --git a/.config/constraints.txt b/.config/constraints.txt index 7e042f9..12e0310 100644 --- a/.config/constraints.txt +++ b/.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 diff --git a/.config/dictionary.txt b/.config/dictionary.txt index c024305..8da68c7 100644 --- a/.config/dictionary.txt +++ b/.config/dictionary.txt @@ -19,6 +19,7 @@ commitlint devel dists docstrings +endraw fontawesome htmlproofer inlinehilite diff --git a/.config/requirements.in b/.config/requirements.in index 8c3167e..2aeff95 100644 --- a/.config/requirements.in +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e47647c..34afd7c 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/docs/README.md b/docs/README.md index 7cc3f6b..fc78f5e 100644 --- a/docs/README.md +++ b/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/) diff --git a/docs/macros.md b/docs/macros.md new file mode 100644 index 0000000..7c65d57 --- /dev/null +++ b/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") }} diff --git a/linkcheckerrc b/linkcheckerrc index 6b60684..17a7b7f 100644 --- a/linkcheckerrc +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 0edd119..c820584 100644 --- a/mkdocs.yml +++ b/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])' diff --git a/pyproject.toml b/pyproject.toml index c99d821..5439c00 100644 --- a/pyproject.toml +++ b/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 diff --git a/src/mkdocs_ansible/__init__.py b/src/mkdocs_ansible/__init__.py index 9e7cfd6..69732a3 100644 --- a/src/mkdocs_ansible/__init__.py +++ b/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)