From d31e55de5c950bd139026d37966a210ca255f6b3 Mon Sep 17 00:00:00 2001 From: Shatakshi Mishra Date: Thu, 9 Nov 2023 20:07:09 +0530 Subject: [PATCH] Initial mkdocs setup (#234) --- .config/requirements-docs.txt | 2 + .github/workflows/tox.yml | 1 + .gitignore | 2 + .readthedocs.yml | 25 +++++++++ cspell.config.yaml | 3 ++ docs/index.md | 15 ++++++ mkdocs.yml | 98 +++++++++++++++++++++++++++++++++++ pyproject.toml | 1 + requirements.txt | 97 +++++++++++++++++++++++++++------- tox.ini | 23 +++++--- 10 files changed, 241 insertions(+), 26 deletions(-) create mode 100644 .config/requirements-docs.txt create mode 100644 .readthedocs.yml create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/.config/requirements-docs.txt b/.config/requirements-docs.txt new file mode 100644 index 0000000..77dfef0 --- /dev/null +++ b/.config/requirements-docs.txt @@ -0,0 +1,2 @@ +mkdocs-ansible[lock]>=0.2.0 +pipdeptree>=2.7.1 diff --git a/.github/workflows/tox.yml b/.github/workflows/tox.yml index 8caeb64..9a2c4a4 100644 --- a/.github/workflows/tox.yml +++ b/.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 }} diff --git a/.gitignore b/.gitignore index b58ef2b..ede4ae9 100644 --- a/.gitignore +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..78a84d9 --- /dev/null +++ b/.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 diff --git a/cspell.config.yaml b/cspell.config.yaml index 1d7f78f..6af5212 100644 --- a/cspell.config.yaml +++ b/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 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..614d902 --- /dev/null +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..9b33b55 --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 13cc49d..bc7e370 100644 --- a/pyproject.toml +++ b/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"] } diff --git a/requirements.txt b/requirements.txt index 0f5ace7..8f30063 100644 --- a/requirements.txt +++ b/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 diff --git a/tox.ini b/tox.ini index cff0f21..420d536 100644 --- a/tox.ini +++ b/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