Replace sphinx with mkdocs (#2942)

Related: ansible/team-devtools#100

.config/dictionary.txt

@@ -47,6 +47,7 @@ autodetected
 autodiscovery
 autodoc
 autofix
+autorefs
 autoupdate
 awcrosby
 backports
@@ -118,6 +119,7 @@ ematchtestfile
 envrc
 execnet
 extlinks
+facelessuser
 facter
 fakerole
 fileglob
@@ -126,6 +128,7 @@ filesspot
 filetree
 fips
 firewalld
+fontawesome
 formatstr
 formetting
 formsyntax
@@ -149,8 +152,8 @@ hwcksum
 idempotency
 importlib
 iniconfig
+inlinehilite
 insertafter
-intersphinx
 ipwrap
 isclass
 iscsi
@@ -173,12 +176,14 @@ libbzip
 libera
 libyaml
 lineinfile
+linenums
 linkcheck
 lintable
 lintables
 literalinclude
 localectl
 machinectl
+magiclink
 markdownlint
 matchdir
 matcherror
@@ -191,6 +196,7 @@ maxdepth
 minversion
 mkdir
 mkdocs
+mkdocstrings
 mkdtemp
 mockings
 mockreturn
@@ -247,6 +253,8 @@ pyenv
 pygments
 pylint
 pylintrc
+pymdown
+pymdownx
 pypa
 pyparsing
 pypi
@@ -296,7 +304,6 @@ skiputils
 slaveinput
 sortfunc
 sourcegraph
-sphinxcontrib
 srpm
 ssbarnea
 stylesheet
@@ -307,6 +314,7 @@ subschema
 subschemas
 substrs
 subtest
+superfences
 supervisorctl
 synchronize
 sysvinit

.config/requirements-docs.txt

@@ -1,8 +1,11 @@
-myst-parser >= 0.16.1
-pipdeptree >= 2.2.1
-sphinx >= 4.4.0
-sphinx-ansible-theme >= 0.9.1
-sphinx-rtd-theme >= 1.0.0, < 2.0.0 # 1.0.0 broke rendering
-sphinxcontrib-apidoc >= 0.3.0
-sphinxcontrib-programoutput2 >= 2.0a1
-
+cairosvg
+markdown-exec>=1.0.0
+mkdocs-gen-files>=0.4.0
+mkdocs-material-extensions>=1.1.1
+mkdocs-material>=9.0.6
+mkdocs>=1.4.2
+mkdocstrings-python>=0.8.3
+mkdocstrings>=0.20.0
+pillow
+pipdeptree>=2.3.3
+pymdown-extensions>=9.9.2

.config/requirements.txt

@@ -4,47 +4,57 @@
 #
 #    pip-compile --extra=docs --extra=test --no-annotate --output-file=.config/requirements.txt --resolver=backtracking --strip-extras --unsafe-package=ansible-core pyproject.toml
 #
-alabaster==0.7.13
 ansible-compat==2.2.7
-ansible-pygments==0.1.1
 astroid==2.13.2
 attrs==22.2.0
-babel==2.11.0
 black==22.12.0
 bracex==2.3.post1
+cairocffi==1.4.0
+cairosvg==2.6.0
 certifi==2022.12.7
 cffi==1.15.1
 charset-normalizer==3.0.1
 click==8.1.3
+colorama==0.4.6
 coverage==7.0.5
 coverage-enable-subprocess==1.0
 cryptography==39.0.0
+cssselect2==0.7.0
+defusedxml==0.7.1
 dill==0.3.6
-docutils==0.17.1
 exceptiongroup==1.1.0
 execnet==1.9.0
 filelock==3.9.0
 flake8==6.0.0
 flake8-future-annotations==1.0.0
+ghp-import==2.1.0
+griffe==0.25.4
 idna==3.4
-imagesize==1.4.1
 importlib-metadata==6.0.0
 iniconfig==2.0.0
 isort==5.11.4
 jinja2==3.1.2
 jsonschema==4.17.3
 lazy-object-proxy==1.9.0
+markdown==3.3.7
+markdown-exec==1.0.0
 markdown-it-py==2.1.0
 markupsafe==2.1.1
 mccabe==0.7.0
-mdit-py-plugins==0.3.3
 mdurl==0.1.2
+mergedeep==1.3.4
+mkdocs==1.4.2
+mkdocs-autorefs==0.4.1
+mkdocs-gen-files==0.4.0
+mkdocs-material==9.0.6
+mkdocs-material-extensions==1.1.1
+mkdocstrings==0.20.0
+mkdocstrings-python==0.8.3
 mypy==0.991
 mypy-extensions==0.4.3
-myst-parser==0.18.1
 packaging==23.0
 pathspec==0.10.3
-pbr==5.11.1
+pillow==9.4.0
 pipdeptree==2.3.3
 platformdirs==2.6.2
 pluggy==1.0.0
@@ -54,37 +64,32 @@ pycparser==2.21
 pyflakes==3.0.1
 pygments==2.14.0
 pylint==2.15.10
+pymdown-extensions==9.9.2
 pyrsistent==0.19.3
 pytest==7.2.1
 pytest-mock==3.10.0
 pytest-plus==0.4.0
 pytest-xdist==3.1.0
-pytz==2022.7.1
+python-dateutil==2.8.2
 pyyaml==6.0
+pyyaml-env-tag==0.1
+regex==2022.10.31
 requests==2.28.2
 resolvelib==0.8.1
 rich==13.2.0
 ruamel-yaml==0.17.21
 ruamel-yaml-clib==0.2.7
 setuptools==66.0.0
-snowballstemmer==2.2.0
-sphinx==5.3.0
-sphinx-ansible-theme==0.10.1
-sphinx-rtd-theme==1.1.1
-sphinxcontrib-apidoc==0.3.0
-sphinxcontrib-applehelp==1.0.3
-sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==2.0.0
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-programoutput2==2.0a1
-sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.5
+six==1.16.0
 subprocess-tee==0.4.1
+tinycss2==1.2.1
 tomli==2.0.1
 tomlkit==0.11.6
 typing-extensions==4.4.0
 urllib3==1.26.14
+watchdog==2.2.1
 wcmatch==8.4.1
+webencodings==0.5.1
 wrapt==1.14.1
 yamllint==1.29.0
 zipp==3.11.0

.gitignore

@@ -64,7 +64,8 @@ src/ansiblelint/_version.py
 .pytest_cache
 test/eco/CODENOTIFY.html
 test/eco
-docs/profiles.md
 test/schemas/node_modules
 .envrc
 collections
+site
+_readthedocs

.pre-commit-config.yaml

@@ -198,7 +198,6 @@ repos:
           - pyyaml
           - rich>=13.2.0
           - ruamel.yaml
-          - sphinx
           - typing_extensions
           - wcmatch
           - yamllint

.readthedocs.yml

@@ -1,52 +1,23 @@
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html
-# for details
-
 ---
-# Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  # keep dirhtml for nice URLs without .html extension
-  builder: dirhtml
-  configuration: docs/conf.py
+mkdocs:
   fail_on_warning: true
-
-# Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
-#  fail_on_warning: true
-
-# Optionally build your docs in additional formats
-# such as PDF and ePub
-formats: []
-
-submodules:
-  include: all # []
-  exclude: []
-  recursive: true
+  configuration: mkdocs.yml
 
 build:
-  # when using pre_build, "image:" is not supported and os and tools are required
   os: ubuntu-22.04
   tools:
-    python: "3.10"
-  jobs:
-    pre_build:
-      - pip install '.[docs,test]'
-      - ansible-lint -L -f docs
-# Optionally set the version of Python and requirements required
-# to build docs
-# python:
-#   version: "3.9"
-#   install:
-#     # On https://readthedocs.org/dashboard/ansible-lint/environmentvariables/ we
-#     # do have PIP_CONSTRAINTS=.config/requirements.txt which ensures we install only
-#     # pinned requirements that that we know to be working.
-#     - method: pip
-#       path: .
-#       extra_requirements:
-#         - docs
-#         - test
-#   system_packages: false
+    python: "3.11"
+  commands:
+    - pip install --user tox
+    - python3 -m tox -e docs -- --strict --site-dir=_readthedocs/html/
+python:
+  system_packages: false
+  install:
+    - method: pip
+      path: tox
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

a.ansi

@@ -0,0 +1 @@
+Hello World