Setup mkdocs

.config/requirements-docs.txt

@@ -0,0 +1 @@
+mkdocs-ansible>=0.2.0

.github/workflows/tox.yml

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

.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

@@ -27,6 +27,7 @@ ignorePaths:
   - tox.ini
   # Sample tox configurations
   - docs/*.ini
+  - mkdocs.yml
 
 languageSettings:
   - languageId: python

docs/index.md

@@ -0,0 +1,64 @@
+# Ansible Development Environment
+
+A pip-like install for Ansible collections.
+
+## Features
+
+- Promotes an "ephemeral" development approach
+- Ensures the current development environment is isolated
+- Install all collection python requirements
+- Install all collection test requirements
+- Checks for missing system packages
+- Symlinks the current collection into the current python interpreter's site-packages
+- Install all collection collection dependencies into the current python interpreter's site-packages
+
+By placing collections into the python site-packages directory they are discoverable by ansible as well as python and pytest.
+
+## Usage
+
+### Setting up a development environment
+
+```
+$ pip install ansible-development-environment --user
+$ git clone <collection_repo>
+$ cd <collection_repo>
+$ ansible-development-environment install -e .\[test] --venv venv
+INFO: Found collection name: network.interfaces from /home/bthornto/github/network.interfaces/galaxy.yml.
+INFO: Creating virtual environment: /home/bthornto/github/network.interfaces/venv
+INFO: Virtual environment: /home/bthornto/github/network.interfaces/venv
+INFO: Using specified interpreter: /home/bthornto/github/network.interfaces/venv/bin/python
+INFO: Requirements file /home/bthornto/github/network.interfaces/requirements.txt is empty, skipping
+INFO: Installing python requirements from /home/bthornto/github/network.interfaces/test-requirements.txt
+INFO: Installing ansible-core.
+INFO: Initializing build directory: /home/bthornto/github/network.interfaces/build
+INFO: Copying collection to build directory using git ls-files.
+INFO: Running ansible-galaxy to build collection.
+INFO: Running ansible-galaxy to install collection and it's dependencies.
+INFO: Removing installed /home/bthornto/github/network.interfaces/venv/lib64/python3.11/site-packages/ansible_collections/network/interfaces
+INFO: Symlinking /home/bthornto/github/network.interfaces/venv/lib64/python3.11/site-packages/ansible_collections/network/interfaces to /home/bthornto/github/network.interfaces
+WARNING: A virtual environment was specified but has not been activated.
+WARNING: Please activate the virtual environment:
+source venv/bin/activate
+```
+
+### Tearing down the development environment
+
+```
+$ ansible-development-environment uninstall ansible.scm
+INFO     Found collection name: ansible.scm from /home/bthornto/github/ansible.scm/galaxy.yml.
+INFO     Requirements file /home/bthornto/github/ansible.scm/requirements.txt is empty, skipping
+INFO     Uninstalling python requirements from /home/bthornto/github/ansible.scm/test-requirements.txt
+INFO     Removed ansible.utils: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible/utils
+INFO     Removed ansible.utils*.info: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible.utils-2.10.3.info
+INFO     Removed ansible.scm: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible/scm
+INFO     Removed collection namespace root: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible
+INFO     Removed collection root: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections
+```
+
+## Help
+
+`ansible-development-environment --help`
+
+`ansible-development-environment install --help`
+
+`ansible-development-environment uninstall --help`

mkdocs.yml

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

@@ -258,6 +258,7 @@ convention = "pep257"
 [tool.setuptools.dynamic]
 dependencies = {file = [".config/requirements.in"]}
 optional-dependencies.dev = {file = [".config/requirements-dev.txt"]}
+optional-dependencies.docs = {file = [".config/requirements-docs.txt"]}
 optional-dependencies.test = {file = [".config/requirements-test.txt"]}
 
 [tool.setuptools_scm]

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_*
@@ -34,10 +35,8 @@ commands =
     coverage run -m pytest {posargs}
     sh -c "coverage combine -q .tox/.coverage.* && coverage xml || true && coverage report"
 allowlist_externals =
-    coverage
     rm
     sh
-envlist = lint, py, packaging, report, clean
 
 [testenv:lint]
 description = Enforce quality standards under {basepython} ({envpython})
@@ -62,6 +61,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