Initial mkdocs setup

.config/requirements-docs.txt

@@ -0,0 +1,2 @@
+mkdocs-ansible[lock]>=0.2.0
+pipdeptree>=2.7.1

.github/workflows/tox.yml

@@ -30,6 +30,7 @@ jobs:
           default_python: "3.11" # used by jobs in other_names
           other_names: |
             lint
+            docs
 
   tox:
     name: ${{ matrix.name }} / python ${{ matrix.python_version }}

.gitignore

@@ -161,3 +161,5 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+_readthedocs

.readthedocs.yml

@@ -0,0 +1,25 @@
+---
+version: 2
+
+mkdocs:
+  fail_on_warning: true
+  configuration: mkdocs.yml
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - pip install --user tox
+    - python3 -m tox -e docs -- --strict --site-dir=_readthedocs/html/
+python:
+  install:
+    - method: pip
+      path: tox
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+submodules:
+  include: all
+  recursive: true

cspell.config.yaml

@@ -25,6 +25,9 @@ ignorePaths:
   - requirements.txt
   # The tox configuration file
   - tox.ini
+  # The mkdocs configuration file
+  - mkdocs.yml
+  - "*.svg"
   # Sample tox configurations
   - docs/*.ini
 

docs/index.md

@@ -0,0 +1,15 @@
+# Tox Ansible Documentation
+
+## About Tox Ansible
+
+`tox-ansible` is a utility designed to simplify the testing of ansible content collections.
+
+Implemented as `tox` plugin, `tox-ansible` provides a simple way to test ansible content collections across multiple python interpreter and ansible versions.
+
+`tox-ansible` uses familiar python testing tools to perform the actual testing. It uses `tox` to create and manage the testing environments, `ansible-test sanity` to run the sanity tests, and `pytest` to run the unit and integration tests. This eliminated the black box nature of other approaches and allows for more control over the testing process.
+
+When used on a local development system, each of the environments are left intact after a test run. This allows for easy debugging of failed tests for a given test type, python interpreter and ansible version.
+
+By using `tox` to create and manage the testing environments, Test outcomes should always be the same on a local development system as they are in a CI/CD pipeline.
+
+`tox` virtual environments are created in the `.tox` directory. These are easily deleted and recreated if needed.

mkdocs.yml

@@ -0,0 +1,98 @@
+---
+site_name: Tox Ansible Documentation
+site_url: https://ansible.readthedocs.io/projects/tox-ansible/
+repo_url: https://github.com/ansible/tox-ansible
+edit_uri: blob/main/docs/
+copyright: Copyright © 2023 Red Hat, Inc.
+docs_dir: docs
+strict: true
+
+theme:
+  name: ansible
+  features:
+    - content.code.copy
+    - content.action.edit
+    - navigation.expand
+    - navigation.sections
+    - navigation.instant
+    - navigation.indexes
+    - navigation.tracking
+    - toc.integrate
+
+extra:
+  social:
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/tox-ansible/
+      name: PyPI
+    - icon: fontawesome/solid/scroll
+      link: https://github.com/ansible/tox-ansible/releases
+      name: Releases
+    - icon: simple/mastodon
+      link: https://fosstodon.org/@ansible
+      name: Mastodon
+    - icon: simple/matrix
+      link: https://matrix.to/#/#devtools:ansible.com
+      name: Matrix
+    - icon: fontawesome/solid/comments
+      link: https://github.com/ansible/tox-ansible/discussions
+      name: Discussions
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/ansible/tox-ansible
+      name: GitHub
+
+nav:
+  - Home: index.md
+
+plugins:
+  - autorefs
+  - markdown-exec
+  - material/search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - material/social
+  - material/tags
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            # Sphinx is for historical reasons, but we could consider switching if needed
+            # https://mkdocstrings.github.io/griffe/docstrings/
+            docstring_style: sphinx
+            merge_init_into_class: yes
+            show_submodules: yes
+          import:
+            - url: https://docs.ansible.com/ansible/latest/objects.inv
+              domains: [py, std]
+
+markdown_extensions:
+  - markdown_include.include:
+      base_path: docs
+  - admonition
+  - def_list
+  - footnotes
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.magiclink:
+      repo_url_shortener: true
+      repo_url_shorthand: true
+      social_url_shorthand: true
+      social_url_shortener: true
+      user: facelessuser
+      repo: pymdown-extensions
+      normalize_issue_symbols: true
+  - pymdownx.tabbed:
+      alternate_style: true
+  - toc:
+      toc_depth: 2
+      permalink: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+        - name: python
+          class: python
+          validator: !!python/name:markdown_exec.validator
+          format: !!python/name:markdown_exec.formatter

pyproject.toml

@@ -40,6 +40,7 @@ dynamic = ["dependencies", "optional-dependencies", "version"]
 tox-ansible = "tox_ansible.plugin"
 
 [tool.setuptools.dynamic]
+optional-dependencies.docs = { file = [".config/requirements-docs.txt"] }
 optional-dependencies.dev = { file = [".config/requirements-dev.txt"] }
 optional-dependencies.test = { file = [".config/requirements-test.txt"] }
 dependencies = { file = [".config/requirements.in"] }

requirements.txt

@@ -1,29 +1,86 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
-# by the following command:
+# This file is autogenerated by pip-compile with Python 3.10
+# To update, run:
 #
-#    pip-compile --extra=docs --extra=test --no-annotate --output-file=requirements.txt
+#    pip-compile --extra=docs --extra=test --no-annotate --output-file=requirements.txt --resolver=backtracking --strip-extras --unsafe-package=resolvelib --unsafe-package=ruamel-yaml-clib pyproject.toml
 #
-cachetools==5.3.0
-cfgv==3.3.1
-chardet==5.1.0
+babel==2.12.1
+beautifulsoup4==4.12.2
+cachetools==5.3.2
+cairocffi==1.6.1
+cairosvg==2.7.1
+certifi==2023.7.22
+cffi==1.16.0
+chardet==5.2.0
+charset-normalizer==3.2.0
+click==8.1.7
 colorama==0.4.6
-distlib==0.3.6
-execnet==1.9.0
-filelock==3.12.0
-identify==2.5.23
+coverage==7.3.2
+cryptography==41.0.5
+csscompressor==0.9.5
+cssselect2==0.7.0
+defusedxml==0.7.1
+distlib==0.3.7
+exceptiongroup==1.1.3
+execnet==2.0.2
+filelock==3.12.4
+ghp-import==2.1.0
+griffe==0.36.4
+htmlmin2==0.1.13
+idna==3.4
+importlib-metadata==6.8.0
 iniconfig==2.0.0
-nodeenv==1.7.0
+jinja2==3.1.2
+jsmin==3.0.1
+markdown==3.4.4
+markdown-exec==1.6.0
+markdown-include==0.8.1
+markupsafe==2.1.3
+mergedeep==1.3.4
+mkdocs==1.5.3
+mkdocs-ansible==0.2.0
+mkdocs-autorefs==0.5.0
+mkdocs-gen-files==0.5.0
+mkdocs-htmlproofer-plugin==1.0.0
+mkdocs-material==9.4.2
+mkdocs-material-extensions==1.2
+mkdocs-minify-plugin==0.7.1
+mkdocs-monorepo-plugin==1.0.5
+mkdocstrings==0.23.0
+mkdocstrings-python==1.7.1
 packaging==23.1
-platformdirs==3.5.0
-pluggy==1.0.0
-pre-commit==3.2.2
-pyproject-api==1.5.1
-pytest==7.3.1
-pytest-xdist==3.2.1
+paginate==0.5.6
+pathspec==0.11.2
+pillow==10.0.1
+pipdeptree==2.13.0
+platformdirs==3.10.0
+pluggy==1.3.0
+pycparser==2.21
+pygments==2.16.1
+pymdown-extensions==10.3
+pyproject-api==1.6.1
+pytest==7.4.3
+pytest-ansible==4.1.1
+pytest-mock==3.12.0
+pytest-xdist==3.3.1
+python-dateutil==2.8.2
+python-slugify==8.0.1
 pyyaml==6.0.1
-tox==4.5.1
-virtualenv==20.23.0
+pyyaml-env-tag==0.1
+regex==2023.8.8
+requests==2.31.0
+six==1.16.0
+soupsieve==2.5
+text-unidecode==1.3
+tinycss2==1.2.1
+tomli==2.0.1
+tox==4.11.3
+typing-extensions==4.8.0
+urllib3==2.0.5
+virtualenv==20.24.6
+watchdog==3.0.0
+webencodings==0.5.1
+zipp==3.17.0
 
 # The following packages are considered to be unsafe in a requirements file:
-# setuptools
+# resolvelib

tox.ini

@@ -5,14 +5,15 @@ env_list =
     py
     lint
     pkg
-no_package = true
+    docs
 skip_missing_interpreters = true
 work_dir = {env:TOX_WORK_DIR:.tox}
 
 [testenv]
 description = Run pytest under {basepython} ({envpython})
-deps =
-    --editable .[test]
+package = editable
+extras =
+    test
 pass_env =
     CI
     CONTAINER_*
@@ -37,16 +38,14 @@ allowlist_externals =
     coverage
     rm
     sh
-envlist = lint, py, packaging, report, clean
 
 [testenv:lint]
 description = Enforce quality standards under {basepython} ({envpython})
+skip_install = true
 deps =
-    --editable .
     pre-commit
 commands =
     pre-commit run --show-diff-on-failure --all-files
-install_command = pip install {opts} {packages}
 
 [testenv:pkg]
 description =
@@ -63,6 +62,18 @@ commands =
       {toxinidir}
     sh -c "python -m twine check --strict {toxinidir}/dist/*"
 
+[testenv:docs]
+description = Builds docs
+package = editable
+skip_install = false
+extras =
+    docs
+set_env =
+    NO_COLOR = 1
+    TERM = dump
+commands =
+    mkdocs build {posargs:}
+
 [testenv:clean]
 description = Erase coverage data
 skip_install = true