Suggest adt installation (#4154)

Reference: AAP-19818

.config/requirements-docs.txt

@@ -1,3 +1,3 @@
-mkdocs-ansible>=24.2.1
+mkdocs-ansible>=24.3.0
 pipdeptree>=2.4.0
 linkchecker>=10.4.0

docs/ci.md

@@ -12,6 +12,8 @@ pipeline, much like any others, that's built into GitHub.
 An action to clone a repo as `molecule_demo`, and run `molecule test` in
 ubuntu.
 
+{% raw %}
+
 ```yaml
 ---
 name: Molecule Test
@@ -41,20 +43,26 @@ jobs:
           molecule test
 ```
 
+{% endraw %}
+
 If you need access to requirements in private repositories, [create a
 token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
 with the required privileges, then define a `GIT_CREDENTIALS` secret for
 your repository with a value looking like
 `https://username:token@github.com/`, and finally add the
 following step before "Test with molecule".
 
+{% raw %}
+
 ```yaml
 - name: Setup git credentials
   uses: fusion-engineering/setup-git-credentials@v2
   with:
-    credentials: ${{secrets.GIT_CREDENTIALS}}
+    credentials: ${{ secrets.GIT_CREDENTIALS }}
 ```
 
+{% endraw %}
+
 ## Travis CI
 
 [Travis](https://travis-ci.com/) is a CI platform, which can be used to
@@ -327,11 +335,13 @@ pipeline {
     of the role root directory. For example :
 
     ``` yaml
+    {% raw %}
     ---
     - name: Converge
       hosts: all
       roles:
         - role: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') | basename }}"
+    {% endraw %}
     ```
 
     This is the cleaner of the current choices. See

docs/guides/docker-rootless.md

@@ -17,6 +17,7 @@ variable `SUDO_GROUP` depends on the target distribution as Debian uses `sudo`
 instead of `wheel` group.
 
 ```docker
+{% raw %}
 # Create `ansible` user with sudo permissions and membership in `DEPLOY_GROUP`
 # This template gets rendered using `loop: "{{ molecule_yml.platforms }}"`, so
 # each `item` is an element of platforms list from the molecule.yml file for this scenario.
@@ -29,6 +30,7 @@ RUN set -xe \
   && usermod -aG ${SUDO_GROUP} ${ANSIBLE_USER} \
   && usermod -aG ${DEPLOY_GROUP} ${ANSIBLE_USER} \
   && sed -i "/^%${SUDO_GROUP}/s/ALL\$/NOPASSWD:ALL/g" /etc/sudoers
+{% endraw %}
 ```
 
 Modify `provisioner.inventory` in `molecule.yml` as follows:

docs/installation.md

@@ -1,7 +1,7 @@
 # Installation
 
-This document assumes the developer has a basic understanding of python
-packaging, and how to install and manage python on the system executing
+This document assumes the developer has a basic understanding of Python
+packaging, and how to install and manage Python on the system executing
 Molecule.
 
 ## Requirements
@@ -28,27 +28,17 @@ packages.
 
 [pip] is the only supported installation method.
 
-!!! warning
-
-    Ansible is not listed as a direct dependency of molecule package because
-    we only call it as a command line tool. You may want to install it using
-    your distribution package installer.
+{{ install_from_adt("ansible-navigator") }}
 
 ```bash
 $ python3 -m pip install molecule ansible-core
 ```
 
-!!! warning
-
-    `ansible` and `ansible-base` pip **extras** were removed in molecule
-    `4.0.0`. If you used them, please switch to explicit package mention to
-    avoid problem with newer versions of molecule.
-
 Keep in mind that on selinux supporting systems, if you install into a
 virtual environment, you may face [issue 34340](https://github.com/ansible/ansible/issues/34340) even if
 selinux is not enabled or is configured to be permissive.
 
-It is your responsibility to assure that soft dependencies of Ansible
+It is your responsibility to ensure that soft dependencies of Ansible
 are available on your controller or host machines.
 
 !!! warning
@@ -67,8 +57,7 @@ $ python3 -m pip install --upgrade --user setuptools
 ### Requirements
 
 Depending on the driver chosen, you may need to install additional
-python packages. See the driver's documentation or `INSTALL.rst`, which
-is created when initializing a new scenario.
+Python packages. See the driver's documentation in that case.
 
 ### Install
 
@@ -107,17 +96,17 @@ usually in `PATH`. Users should know that molecule can also be called as
 a python module, using `python -m molecule ...`. This alternative method
 has some benefits:
 
-- allows to explicitly control which python interpreter is used by
+- allows to explicitly control which Python interpreter is used by
   molecule
-- allows molecule installation at user level without even needing to
+- allows molecule installation at the user level without even needing to
   have the script in `PATH`.
 
 ## Container
 
-Molecule is built into a container image by the [Ansible Creator Execution
+`Molecule` is built into a container image by the [Ansible Creator Execution
 Environment](https://github.com/ansible/creator-ee) project, `creator-ee`.
 
-Any questions or bugs related to use of Molecule from within a container
+Any questions or bugs related to the use of Molecule from within a container
 should be addressed by the Ansible Creator Execution Environment
 project.
 
@@ -129,9 +118,8 @@ Follow the instructions below to do the initial install and subsequent
 updates.
 
 The package distribution that you'll get installed will be
-autogenerated and will contain a commit hash information making it
-easier to refer to certain unstable version should the need to send a
-bug report arise.
+autogenerated and will contain commit hash information, making it
+easier to refer to.
 
 ### Requirements
 

mkdocs.yml

@@ -72,6 +72,7 @@ nav:
       - guides/custom-image.md
       - guides/docker-rootless.md
       - guides/monolith.md
+      - guides/inside-a-container.md
       - guides/parallel.md
       - guides/podman-inside-docker.md
       - guides/sharing.md
@@ -81,6 +82,8 @@ nav:
 
 plugins:
   - autorefs
+  - macros:
+      modules: [mkdocs-ansible:mkdocs_ansible]
   - material/search:
       separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
   - material/social

pyproject.toml

@@ -76,7 +76,7 @@ profile = "black"
 known_first_party = "molecule"
 
 [tool.mypy]
-python_version = 3.10
+python_version = "3.10"
 # strict = true
 color_output = true
 error_summary = true
@@ -222,9 +222,7 @@ known-first-party = ["molecule"]
 [tool.setuptools.dynamic]
 optional-dependencies.docs = { file = [".config/requirements-docs.txt"] }
 optional-dependencies.test = { file = [".config/requirements-test.txt"] }
-optional-dependencies.testinfra = { file = [
-  ".config/requirements-testinfra.txt",
-] }
+optional-dependencies.testinfra = { file = [".config/requirements-testinfra.txt"] }
 dependencies = { file = [".config/requirements.in"] }
 
 [tool.setuptools_scm]

tox.ini

@@ -86,8 +86,8 @@ description = Build documentation
 passenv = *
 usedevelop = true
 commands =
-    linkchecker -f linkcheckerrc docs
-    mkdocs build -c --strict {posargs:}
+    linkchecker -q -f linkcheckerrc docs
+    mkdocs {posargs:build -c --strict}
 extras =
     docs