Convert sphinx based documentation to mkdocs

.config/dictionary.txt

@@ -1,12 +1,3 @@
-cliconf             # Ansible network cli abstraction plugin
-kegex               # An action's regex
-netcommon           # Ansible network collection, seen in tests and README
-setuptools          # Used in _version.pyi
-Towncrier           # Changelog generator
-
-mqueue              # https://github.com/ansible/ansible-runner/issues/984
-
-
 COLORTERM
 ESCDELAY
 Kolkata
@@ -17,6 +8,7 @@ Representer
 Rocannon's
 SCAP
 SIGTERM
+Towncrier           # Changelog generator
 ansiblelint
 apidoc
 argname
@@ -25,8 +17,10 @@ argparser
 argspec
 argvalues
 astimezone
+autorefs
 basesystem
 caplog
+cliconf             # Ansible network cli abstraction plugin
 codeclimate
 colname
 coltext
@@ -42,29 +36,41 @@ dumpable
 dunder
 editables
 extlinks
+facelessuser
 fedoraproject
+fontawesome
 fromlist
+headerlink
 helpconfig
 hostvars
+hrefs
+htmlproofer
 httpapi
 importables
+inlinehilite
 intersphinx
 introspector
 isatty
 jsonschema
 keepends
+kegex               # An action's regex
 kegexes
 lentext
 levelname
 libonig
 lightbulbs
+linenums
 linkcheck
 lintable
 lintables
+magiclink
 maskables
 maxsplit
+mkdocstrings
 moduleauthor
+mqueue              # https://github.com/ansible/ansible-runner/issues/984
 myproject
+netcommon           # Ansible network collection, seen in tests and README
 netconf
 nitpicky
 nonblocking
@@ -78,19 +84,22 @@ preclear
 precommand
 premanent
 pullable
+pymdown
+pymdownx
 redhatinsights
 representer
 returndocs
 runtimes
 scrollback
 sectionauthor
+setuptools          # Used in _version.pyi
 smartquotes
 somevalue
-sphinxcontrib
 statemachine
 stripspaces
 subaction
 subschema
+superfences
 templatable
 templated
 templating
@@ -104,3 +113,4 @@ userbase
 viewcode
 volmount
 workdir
+xmss

.github/CONTRIBUTING.md

@@ -3,68 +3,68 @@
 Some background:
 
 The ansible-navigator code base is not just for it's users but current and
-future developers. Over time we have adopted a few tools that help us
-maintain it and you contribute.
+future developers. Over time we have adopted a few tools that help us maintain
+it and you contribute.
 
-1. mypy (Helps with type checking)
+1.  mypy (Helps with type checking)
 
-2. pylint (lints all the things)
+2.  pylint (lints all the things)
 
-3. code-spell (prevents typos in code)
+3.  code-spell (prevents typos in code)
 
-4. isort (sorts import statements)
+4.  isort (sorts import statements)
 
-```{note}
-In early development cycles, a decision was made to use black as a formatter
-which is why current pull-requests are required to pass a
-`black --diff` check of the source tree. The decision to use `black` is
-left to individual developers as the formatting changes it makes can be
-achieved without it.
-```
+!!! notice
+
+    In early development cycles, a decision was made to use black as a formatter
+    which is why current pull-requests are required to pass a
+    `black --diff` check of the source tree. The decision to use `black` is
+    left to individual developers as the formatting changes it makes can be
+    achieved without it.
 
-Details can be found below on how to run these manually, our CI will also
-check them for you.
+Details can be found below on how to run these manually, our CI will also check
+them for you.
 
 In order to contribute, you'll need to:
 
-1. Fork the repository.
+1.  Fork the repository.
 
-2. Create a branch, push your changes there.
+2.  Create a branch, push your changes there.
 
-3. Send it to us as a PR.
+3.  Send it to us as a PR.
 
-4. Iterate on your PR, incorporating the requested improvements
-   and participating in the discussions.
+4.  Iterate on your PR, incorporating the requested improvements and
+    participating in the discussions.
 
 Prerequisites:
 
-1. Have {doc}`tox <tox:index>`.
-
-2. Use {doc}`tox <tox:index>` to run the tests.
-
-3. Before sending a PR, make sure that `lint` passes:
-
-   ```shell-session
-   $ tox -e lint
-   lint create: .tox/lint
-   lint installdeps: .[test]
-   lint installed: ...
-   lint run-test-pre: PYTHONHASHSEED='4242713142'
-   lint run-test: commands[0] | pylint ansible_navigator tests ...
-   ...
-   _________________________________ summary __________________________________
-   lint: commands succeeded
-   congratulations :)
-   ```
-
-   ```{tip}
-   Because the version of python is pinned to a specific version to ensure the
-   outcome of running `tox -e lint` locally is the same as `tox -e lint` being run
-   by github actions, you may see the following error: `RuntimeError: failed to
-   find interpreter for Builtin discover of python_spec='python3.XX'`. This
-   indicates the version of python that needs to be installed for tox to run
-   locally.
-   ```
+1.  Have {doc}`tox <tox:index>`.
+
+2.  Use {doc}`tox <tox:index>` to run the tests.
+
+3.  Before sending a PR, make sure that `lint` passes:
+
+    ```shell-session
+    $ tox -e lint
+    lint create: .tox/lint
+    lint installdeps: .[test]
+    lint installed: ...
+    lint run-test-pre: PYTHONHASHSEED='4242713142'
+    lint run-test: commands[0] | pylint ansible_navigator tests ...
+    ...
+    _________________________________ summary __________________________________
+    lint: commands succeeded
+    congratulations :)
+    ```
+
+!!! notice
+
+    Because the version of python is pinned to a specific version to ensure the
+    outcome of running `tox -e lint` locally is the same as `tox -e lint` being run
+    by github actions, you may see the following error: `RuntimeError: failed to
+    find interpreter for Builtin discover of python_spec='python3.XX'`. This
+    indicates the version of python that needs to be installed for tox to run
+    locally. In this case, the version of python that needs to be installed is
 
 ## Debugging Ansible Navigator with VS Code
 
@@ -82,22 +82,21 @@ pip install -e .
 
 Once we are inside vscode with project installed, we should see a `.vscode`
 folder in our workspace. Having a launch configuration file is beneficial
-because it allow us to configure and save debugging setup details. VS Code
-keeps debugging configuration information in a `launch.json` file located in a
+because it allow us to configure and save debugging setup details. VS Code keeps
+debugging configuration information in a `launch.json` file located in a
 `.vscode` folder in our workspace (project root folder).
 
-Similarly, The workspace settings file `settings.json` is also located under
-the `.vscode` folder in our root folder. These are the project specific
-settings shared by all users of that project.
+Similarly, The workspace settings file `settings.json` is also located under the
+`.vscode` folder in our root folder. These are the project specific settings
+shared by all users of that project.
 
 Use the existing settings or drop in the required changes in configuration of
 these `launch.json` and `settings.json` files.
 
 Now, the final steps!
 
 - Put breakpoint(s) in the code where needed.
-- Hover to the **Run and Debug** icon in the Activity Bar to start the
-  debugger.
+- Hover to the **Run and Debug** icon in the Activity Bar to start the debugger.
 
 At this point, the debugger should hit your breakpoint and start the debugging
 session.
@@ -116,7 +115,7 @@ the program to debug) in our launch.json configuration file.
   absolute path to the playbook as mentioned. Following configuration will allow
   to debug `ansible-navigator site.yml --mode stdout`.
 
-```shell-session
+```json
 {
   "version": "0.2.0",
   "configurations": [
@@ -136,7 +135,7 @@ the program to debug) in our launch.json configuration file.
 - Debug `ansible-navigator exec` subcommand using _args_ with some parameter.
   Following configuration will allow to debug `ansible-navigator exec -- pwd`.
 
-```shell-session
+```json
 {
   "version": "0.2.0",
   "configurations": [
@@ -149,12 +148,13 @@ the program to debug) in our launch.json configuration file.
       "cwd": "${workspaceFolder}/src",
       "justMyCode": false
     }
+}
 ```
 
 - To debug subcommand `ansible-navigator images`, add one more attribute as
   `"args": ["images"]` in our previously configured launch.json.
-- To debug subcommand `ansible-navigator collections`, add one more attribute
-  as `"args": ["collections"]` in launch.json, and so on.
+- To debug subcommand `ansible-navigator collections`, add one more attribute as
+  `"args": ["collections"]` in launch.json, and so on.
 - Moreover, to debug subcommands with some parameter use
   `"args": ["subcommand-name", "--", "parameter"]`
 - While debugging any subcommand with arguments, make sure to use one _args_
@@ -168,3 +168,19 @@ the program to debug) in our launch.json configuration file.
 
 [guide]: https://code.visualstudio.com/docs/editor/debugging
 [python debugger]: https://www.geeksforgeeks.org/python-debugger-python-pdb/
+
+## Contributing docs
+
+We use [mkdocs](https://www.mkdocs.org/) to generate our docs website. You can
+trigger the process locally by executing:
+
+<!-- cspell:disable -->
+
+```shell
+$ tox -e docs
+...
+```
+
+It is also integrated with [Read The Docs](https://readthedocs.org/) that builds
+and publishes each commit to the main branch and generates live docs previews
+for each pull request.

.github/ISSUE_TEMPLATE/security_bug_report.md

@@ -4,6 +4,8 @@ about: How to report security vulnerabilities
 labels: new
 ---
 
-For all security related bugs, email security@ansible.com instead of using this issue tracker and you will receive a prompt response.
+For all security related bugs, email security@ansible.com instead of using this
+issue tracker and you will receive a prompt response.
 
-For more information on the Ansible community's practices regarding responsible disclosure, see https://www.ansible.com/security
+For more information on the Ansible community's practices regarding responsible
+disclosure, see https://www.ansible.com/security

.github/SECURITY.md

@@ -2,14 +2,14 @@
 
 ## Supported Versions
 
-Ansible Navigator does not backport security fixes only applying
-them to the main branch and making the next patch release in the stream.
+Ansible Navigator does not backport security fixes only applying them to the
+main branch and making the next patch release in the stream.
 
 ## Reporting a Vulnerability
 
-We encourage responsible disclosure practices for security
-vulnerabilities. Please read our [policies for reporting bugs]
-[bug reports policy] if you want to report a security issue that might affect
-Ansible.
+We encourage responsible disclosure practices for security vulnerabilities.
+Please read our [policies for reporting bugs] [bug reports policy] if you want
+to report a security issue that might affect Ansible.
 
-[bug reports policy]: https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#reporting-a-bug
+[bug reports policy]:
+  https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#reporting-a-bug

.markdownlint.yaml

@@ -0,0 +1,12 @@
+default: true
+
+# We rely on prettier to do the rewrapping of long lines.
+MD013: false
+
+# See https://github.com/prettier/prettier/issues/14515
+MD030:
+  ol_single: 2
+  ol_multi: 2
+
+# Apparently complains about use of '!!! notice'
+MD046: false

.pre-commit-config.yaml

@@ -41,7 +41,7 @@ repos:
         language_version: python3
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v6.28.0
+    rev: v6.29.0
     hooks:
       - id: cspell
         name: Spell check with cspell
@@ -64,8 +64,13 @@ repos:
       - id: check-case-conflict
       - id: check-symlinks
       - id: check-yaml
+        exclude: >
+          (?x)^
+            (
+              mkdocs.yml
+            )
+          $
       - id: detect-private-key
-
       # Heavy checks:
       - id: check-ast
       - id: debug-statements
@@ -88,7 +93,6 @@ repos:
               docs/(
                 faq|
                 index|
-                installation
               )|
               README|
               src/ansible_navigator/data/(help|welcome)
@@ -145,7 +149,6 @@ repos:
           - libtmux
           - pytest
           - pytest-mock
-          - sphinx
           - types-backports
           - types-docutils
           - types-mock
@@ -174,5 +177,4 @@ repos:
           - pytest
           - pytest-mock
           - setuptools-scm
-          - sphinx
         pass_filenames: false