Initial mkdocs setup (#199)

* Initial mkdocs setup

* Add RTD config

---------

Co-authored-by: Sorin Sbarnea <ssbarnea@redhat.com>

.config/requirements-docs.txt

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

.config/requirements.txt

@@ -7,35 +7,85 @@
 ansible-compat==4.1.10
 ansible-core==2.15.5
 attrs==23.1.0
+babel==2.12.1
+beautifulsoup4==4.12.2
 bracex==2.4
+cairocffi==1.6.1
+cairosvg==2.7.1
+certifi==2023.7.22
 cffi==1.16.0
+charset-normalizer==3.2.0
 click==8.1.7
 click-help-colors==0.9.2
+colorama==0.4.6
 coverage==7.3.2
 cryptography==41.0.4
+csscompressor==0.9.5
+cssselect2==0.7.0
+defusedxml==0.7.1
 enrich==1.2.7
 exceptiongroup==1.1.3
+ghp-import==2.1.0
+griffe==0.36.4
+htmlmin2==0.1.13
+idna==3.4
+importlib-metadata==6.8.0
 importlib-resources==5.0.7
 iniconfig==2.0.0
 jinja2==3.1.2
+jsmin==3.0.1
 jsonschema==4.19.1
 jsonschema-specifications==2023.7.1
+markdown==3.4.4
+markdown-exec==1.6.0
+markdown-include==0.8.1
 markdown-it-py==3.0.0
 markupsafe==2.1.3
 mdurl==0.1.2
+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
 molecule==6.0.2
-packaging==23.2
+packaging==23.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
 pytest==7.4.2
+python-dateutil==2.8.2
+python-slugify==8.0.1
 pyyaml==6.0.1
+pyyaml-env-tag==0.1
 referencing==0.30.2
+regex==2023.8.8
+requests==2.31.0
 resolvelib==1.0.1
 rich==13.6.0
 rpds-py==0.10.4
 setuptools==68.2.2
+six==1.16.0
+soupsieve==2.5
 subprocess-tee==0.4.1
+text-unidecode==1.3
+tinycss2==1.2.1
 tomli==2.0.1
 typing-extensions==4.8.0
+urllib3==2.0.5
+watchdog==3.0.0
 wcmatch==8.5
+webencodings==0.5.1
+zipp==3.17.0

.github/workflows/tox.yml

@@ -34,6 +34,7 @@ jobs:
             lint
             pkg
             py310-devel
+            docs
           platforms: linux
 
   build:

.gitignore

@@ -160,11 +160,12 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-
-
 # In contrast to the entries above this line which largely come from
 # the github default, the following have been inidividually rationalized
 # and should all have detailed explanations
 
 # Version created and populated by setuptools_scm
 /src/pytest_ansible/_version.py
+
+.DS_Store
+_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

@@ -19,5 +19,7 @@ ignorePaths:
   - .config/requirements*
   # The tox configuration file
   - tox.ini
+  - mkdocs.yml
+  - "*.svg"
 languageSettings:
   - languageId: python

docs/index.md

@@ -0,0 +1,24 @@
+# Ansible Pytest Documentation
+
+## About Ansible Pytest
+
+The `pytest-ansible` plugin is designed to provide seamless integration between
+`pytest` and `Ansible`, allowing you to efficiently run and test Ansible-related
+tasks and scenarios within your pytest test suite. This plugin enhances the
+testing workflow by offering three distinct pieces of functionality:
+
+1. **Unit Testing for Ansible Collections**: This feature aids in running unit
+   tests for `Ansible collections` using `pytest`. It allows you to validate the
+   behavior of your Ansible `modules` and `roles` in isolation, ensuring that
+   each component functions as expected.
+
+2. **Molecule Scenario Integration**: The plugin assists in running Molecule
+   `scenarios` using `pytest`. This integration streamlines the testing of
+   Ansible roles and playbooks across different environments, making it easier
+   to identify and fix issues across diverse setups.
+
+3. **Ansible Integration for Pytest Tests**: With this functionality, you can
+   seamlessly use `Ansible` from within your `pytest` tests. This opens up
+   possibilities to interact with Ansible components and perform tasks like
+   provisioning resources, testing configurations, and more, all while
+   leveraging the power and flexibility of pytest.

mkdocs.yml

@@ -0,0 +1,98 @@
+---
+site_name: Ansible Pytest Documentation
+site_url: https://ansible.readthedocs.io/projects/pytest-ansible/
+repo_url: https://github.com/ansible/pytest-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/pytest-ansible/
+      name: PyPI
+    - icon: fontawesome/solid/scroll
+      link: https://github.com/ansible/pytest-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/pytest-ansible/discussions
+      name: Discussions
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/ansible/pytest-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

@@ -176,6 +176,7 @@ lines-after-imports = 2 # Ensures consistency for cases when there's variable vs
 lines-between-types = 1 # Separate import/from with 1 line
 
 [tool.setuptools.dynamic]
+optional-dependencies.docs = { file = [".config/requirements-docs.txt"] }
 optional-dependencies.test = { file = [".config/requirements-test.txt"] }
 optional-dependencies.lock = { file = [".config/requirements-lock.txt"] }
 dependencies = { file = [".config/requirements.in"] }

tox.ini

@@ -4,7 +4,8 @@ envlist =
     pkg,
     py,
     devel,
-    coverage
+    coverage,
+    docs
 skip_missing_interpreters = true
 
 [testenv]
@@ -115,3 +116,17 @@ commands =
   python3 -m coverage report
 deps =
   coverage[toml]>=7.0.5
+
+[testenv:docs]
+description = Builds docs
+extras =
+  docs
+setenv =
+  # Disable colors until markdown-exec supports it:
+  # https://github.com/pawamoy/markdown-exec/issues/11
+  NO_COLOR = 1
+  TERM = dump
+skip_install = false
+usedevelop = true
+commands =
+  mkdocs build {posargs:}