Restructure docs

docs/contributing.md

@@ -1,16 +1,10 @@
-# Contributing
-
-- To see what's discussed see the [discussions
-  ](https://github.com/ansible-community/molecule/discussions).
-- Join the Molecule [community working
-  group](https://github.com/ansible/community/wiki/molecule) if you
-  would like to influence the direction of the project.
-- Join us in `#ansible-devtools` on
-  [libera.chat](https://web.libera.chat/?channel=#ansible-molecule) matrix/irc,
-  or [molecule discussions](https://github.com/ansible-community/molecule/discussions).
-- The full list of Ansible email lists and IRC channels can be found in
-  the [communication
-  page](https://docs.ansible.com/ansible/latest/community/communication.html).
+# Contributor Guide
+
+## Code Of Conduct
+
+Please see our [Code of
+Conduct](https://github.com/ansible-community/molecule/blob/main/.github/CODE_OF_CONDUCT.md)
+document.
 
 ## Guidelines
 
@@ -29,12 +23,6 @@
 - Reformat the code by following the formatting section below.
 - Submit a pull request.
 
-## Code Of Conduct
-
-Please see our [Code of
-Conduct](https://github.com/ansible-community/molecule/blob/main/.github/CODE_OF_CONDUCT.md)
-document.
-
 ## Pull Request and Governance
 
 - If your PRs get stuck [join us on

docs/getting-started.md

@@ -114,24 +114,24 @@ The `molecule.yml` is for configuring Molecule. It is a
 [YAML](https://yaml.org/) file whose keys represent the high-level
 components that Molecule provides. These are:
 
-- The [dependency](configuration.md#dependency) manager. Molecule
+- The [dependency](references/configuration.md#dependency) manager. Molecule
   uses [galaxy development guide]
   by default to resolve your role dependencies.
-- The [driver](configuration.md#driver) provider. Molecule uses
-  the [Delegated](configuration.md#delegated) driver by default.
+- The [driver](references/configuration.md#driver) provider. Molecule uses
+  the [Delegated](references/configuration.md#delegated) driver by default.
   Molecule uses the driver to delegate the task of creating instances.
-- The [platforms](configuration.md#platforms) definitions. Molecule
+- The [platforms](references/configuration.md#platforms) definitions. Molecule
   relies on this to know which instances to create, name and to which
   group each instance belongs. If you need to test your role against
   multiple popular distributions (CentOS, Fedora, Debian), you can
   specify that in this section.
-- The [provisioner](configuration.md#provisioner). Molecule only
+- The [provisioner](references/configuration.md#provisioner). Molecule only
   provides an Ansible provisioner. Ansible manages the life cycle of
   the instance based on this configuration.
 - The [scenario][] definition.
   Molecule relies on this configuration to control the scenario
   sequence order.
-- The [verifier](configuration.md#verifier) framework. Molecule
+- The [verifier](references/configuration.md#verifier) framework. Molecule
   uses Ansible by default to provide a way to write specific state
   checking tests (such as deployment smoke tests) on the target
   instance.

docs/faq.md → docs/references/faq.md

@@ -57,7 +57,7 @@ the scenario's molecule.yml.
 
 ## Can I run Molecule processes in parallel?
 
-Please see [parallel-usage-example](examples.md#docker-with-non-privileged-user) for
+Please see [parallel-usage-example](../user_guide/examples.md#docker-with-non-privileged-user) for
 usage.
 
 ## Can I specify random instance IDs in my molecule.yml?
@@ -95,7 +95,7 @@ Yes, roles contained in a
 [monorepo](https://en.wikipedia.org/wiki/Monorepo) with other roles are
 automatically picked up and `ANSIBLE_ROLES_PATH` is set accordingly. See
 [this
-page](examples.md#monolith-repo)
+page](../user_guide/examples.md#monolith-repo)
 for more information.
 
 ## How can I add development/testing-only dependencies?

docs/next.md → docs/references/roadmap.md

@@ -1,6 +1,6 @@
-# Molecule Next
+# Molecule Roadmap
 
-Molecule "next" is the future major version of molecule, one that is currently
+The Molecule roadmap is the future major version of molecule, one that is currently
 available from the main branch. One of the main goals of the new version is to
 reduce the amount of magic and just rely on ansible core features.
 

mkdocs.yml

@@ -35,49 +35,23 @@ extra:
       link: https://github.com/ansible-community/molecule
 
 nav:
-  - Home: index.md
-  - installation.md
-  - Using:
-      - getting-started.md
-      - usage.md
-      - next.md
-      - configuration.md
-      - ci.md
+  - Introduction: index.md
+  - Installation:
+      - installation.md
+  - Getting Started Guide: getting-started.md
+  - User Guide:
+      - user_guide/ci.md
+      - user_guide/examples.md
   - Examples:
-      - docker.md
-      - podman.md
-      - kubevirt.md
-  - examples.md
-  - faq.md
+      - examples/docker.md
+      - examples/podman.md
+      - examples/kubevirt.md
   - contributing.md
-  - Future documentation (WIP):
-      - Introduction: working/introduction/introduction.md
-      - Installation:
-          - working/installation/install.md
-          - working/installation/upgrade.md
-      - Getting Started: working/getting_started/getting_started.md
-      - User Guide:
-          - working/user_guide/understanding.md
-          - working/user_guide/creating_testing_collection.md
-          - working/user_guide/testing_existing_collection.md
-          - working/user_guide/testing_existing_roles.md
-          - working/user_guide/ci_integration.md
-          - working/user_guide/using_tox-ansible.md
-      - References:
-          - working/references/cli.md
-          - working/references/configuration.md
-          - working/references/porting_change_log.md
-          - working/references/road_map.md
-      - Examples:
-          - working/examples/example_1.md
-          - working/examples/example_2.md
-          - working/examples/example_3.md
-      - Frequently asked questions: working/faq/faq.md
-      - Contributor Guide:
-          - working/contributor_guide/code_of_conduct.md
-          - working/contributor_guide/developer_contact.md
-          - working/contributor_guide/environment_setup.md
-          - working/contributor_guide/contribution_requirements.md
+  - References:
+      - references/usage.md
+      - references/configuration.md
+      - references/faq.md
+      - references/roadmap.md
 
 plugins:
   - autorefs