From ea11a5f548e6dfb8fe3fef195d26fab9c22ed63d Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 14 Sep 2023 16:43:58 -0400 Subject: [PATCH] Restructure docs --- docs/contributing.md | 25 +++----- docs/{ => examples}/docker.md | 0 docs/{ => examples}/kubevirt.md | 0 docs/{ => examples}/podman.md | 0 docs/getting-started.md | 12 ++-- docs/{ => references}/configuration.md | 0 docs/{ => references}/faq.md | 4 +- docs/references/porting_guide.md | 1 + docs/{next.md => references/roadmap.md} | 4 +- docs/{ => references}/usage.md | 0 docs/{working/installation => }/upgrade.md | 0 docs/{ => user_guide}/ci.md | 0 docs/{ => user_guide}/examples.md | 0 docs/user_guide/testing_collections.md | 1 + docs/user_guide/testing_roles.md | 1 + docs/user_guide/understanding.md | 1 + docs/user_guide/using_tox_ansible.md | 1 + .../contributor_guide/code_of_conduct.md | 1 - .../contribution_requirements.md | 1 - .../contributor_guide/developer_contact.md | 1 - .../contributor_guide/environment_setup.md | 1 - docs/working/examples/example_1.md | 1 - docs/working/examples/example_2.md | 1 - docs/working/examples/example_3.md | 1 - docs/working/faq/faq.md | 1 - .../getting_started/getting_started.md | 1 - docs/working/installation/install.md | 1 - docs/working/introduction/introduction.md | 1 - docs/working/references/cli.md | 1 - docs/working/references/configuration.md | 1 - docs/working/references/porting_change_log.md | 1 - docs/working/references/road_map.md | 1 - docs/working/user_guide/ci_integration.md | 1 - .../user_guide/creating_testing_collection.md | 1 - .../user_guide/testing_existing_collection.md | 1 - .../user_guide/testing_existing_roles.md | 1 - docs/working/user_guide/understanding.md | 1 - docs/working/user_guide/using_tox-ansible.md | 1 - mkdocs.yml | 62 +++++++------------ 39 files changed, 44 insertions(+), 89 deletions(-) rename docs/{ => examples}/docker.md (100%) rename docs/{ => examples}/kubevirt.md (100%) rename docs/{ => examples}/podman.md (100%) rename docs/{ => references}/configuration.md (100%) rename docs/{ => references}/faq.md (96%) create mode 100644 docs/references/porting_guide.md rename docs/{next.md => references/roadmap.md} (93%) rename docs/{ => references}/usage.md (100%) rename docs/{working/installation => }/upgrade.md (100%) rename docs/{ => user_guide}/ci.md (100%) rename docs/{ => user_guide}/examples.md (100%) create mode 100644 docs/user_guide/testing_collections.md create mode 100644 docs/user_guide/testing_roles.md create mode 100644 docs/user_guide/understanding.md create mode 100644 docs/user_guide/using_tox_ansible.md delete mode 100644 docs/working/contributor_guide/code_of_conduct.md delete mode 100644 docs/working/contributor_guide/contribution_requirements.md delete mode 100644 docs/working/contributor_guide/developer_contact.md delete mode 100644 docs/working/contributor_guide/environment_setup.md delete mode 100644 docs/working/examples/example_1.md delete mode 100644 docs/working/examples/example_2.md delete mode 100644 docs/working/examples/example_3.md delete mode 100644 docs/working/faq/faq.md delete mode 100644 docs/working/getting_started/getting_started.md delete mode 100644 docs/working/installation/install.md delete mode 100644 docs/working/introduction/introduction.md delete mode 100644 docs/working/references/cli.md delete mode 100644 docs/working/references/configuration.md delete mode 100644 docs/working/references/porting_change_log.md delete mode 100644 docs/working/references/road_map.md delete mode 100644 docs/working/user_guide/ci_integration.md delete mode 100644 docs/working/user_guide/creating_testing_collection.md delete mode 100644 docs/working/user_guide/testing_existing_collection.md delete mode 100644 docs/working/user_guide/testing_existing_roles.md delete mode 100644 docs/working/user_guide/understanding.md delete mode 100644 docs/working/user_guide/using_tox-ansible.md diff --git a/docs/contributing.md b/docs/contributing.md index 5433461516..365b74a102 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,16 +1,11 @@ -# 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,11 +24,7 @@ - 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 diff --git a/docs/docker.md b/docs/examples/docker.md similarity index 100% rename from docs/docker.md rename to docs/examples/docker.md diff --git a/docs/kubevirt.md b/docs/examples/kubevirt.md similarity index 100% rename from docs/kubevirt.md rename to docs/examples/kubevirt.md diff --git a/docs/podman.md b/docs/examples/podman.md similarity index 100% rename from docs/podman.md rename to docs/examples/podman.md diff --git a/docs/getting-started.md b/docs/getting-started.md index 09948334bf..22a973219f 100644 --- a/docs/getting-started.md +++ b/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. diff --git a/docs/configuration.md b/docs/references/configuration.md similarity index 100% rename from docs/configuration.md rename to docs/references/configuration.md diff --git a/docs/faq.md b/docs/references/faq.md similarity index 96% rename from docs/faq.md rename to docs/references/faq.md index a4de683d81..ac0c5adb94 100644 --- a/docs/faq.md +++ b/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? diff --git a/docs/references/porting_guide.md b/docs/references/porting_guide.md new file mode 100644 index 0000000000..bfc98c333a --- /dev/null +++ b/docs/references/porting_guide.md @@ -0,0 +1 @@ +# Porting Guide diff --git a/docs/next.md b/docs/references/roadmap.md similarity index 93% rename from docs/next.md rename to docs/references/roadmap.md index c9eba6a8a4..464efc2d01 100644 --- a/docs/next.md +++ b/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. diff --git a/docs/usage.md b/docs/references/usage.md similarity index 100% rename from docs/usage.md rename to docs/references/usage.md diff --git a/docs/working/installation/upgrade.md b/docs/upgrade.md similarity index 100% rename from docs/working/installation/upgrade.md rename to docs/upgrade.md diff --git a/docs/ci.md b/docs/user_guide/ci.md similarity index 100% rename from docs/ci.md rename to docs/user_guide/ci.md diff --git a/docs/examples.md b/docs/user_guide/examples.md similarity index 100% rename from docs/examples.md rename to docs/user_guide/examples.md diff --git a/docs/user_guide/testing_collections.md b/docs/user_guide/testing_collections.md new file mode 100644 index 0000000000..cda943e527 --- /dev/null +++ b/docs/user_guide/testing_collections.md @@ -0,0 +1 @@ +# Testing roles in a collection \ No newline at end of file diff --git a/docs/user_guide/testing_roles.md b/docs/user_guide/testing_roles.md new file mode 100644 index 0000000000..033c79c1c9 --- /dev/null +++ b/docs/user_guide/testing_roles.md @@ -0,0 +1 @@ +# Testing standalone roles \ No newline at end of file diff --git a/docs/user_guide/understanding.md b/docs/user_guide/understanding.md new file mode 100644 index 0000000000..5ec32b8efd --- /dev/null +++ b/docs/user_guide/understanding.md @@ -0,0 +1 @@ +# Understanding Ansible Molecule \ No newline at end of file diff --git a/docs/user_guide/using_tox_ansible.md b/docs/user_guide/using_tox_ansible.md new file mode 100644 index 0000000000..a40247b597 --- /dev/null +++ b/docs/user_guide/using_tox_ansible.md @@ -0,0 +1 @@ +# Using Molecule with tox-ansible \ No newline at end of file diff --git a/docs/working/contributor_guide/code_of_conduct.md b/docs/working/contributor_guide/code_of_conduct.md deleted file mode 100644 index 2fe822c775..0000000000 --- a/docs/working/contributor_guide/code_of_conduct.md +++ /dev/null @@ -1 +0,0 @@ -# Code of conduct diff --git a/docs/working/contributor_guide/contribution_requirements.md b/docs/working/contributor_guide/contribution_requirements.md deleted file mode 100644 index b7a0e84f82..0000000000 --- a/docs/working/contributor_guide/contribution_requirements.md +++ /dev/null @@ -1 +0,0 @@ -# Contributing to molecule diff --git a/docs/working/contributor_guide/developer_contact.md b/docs/working/contributor_guide/developer_contact.md deleted file mode 100644 index f57c660a26..0000000000 --- a/docs/working/contributor_guide/developer_contact.md +++ /dev/null @@ -1 +0,0 @@ -# Developer contacts diff --git a/docs/working/contributor_guide/environment_setup.md b/docs/working/contributor_guide/environment_setup.md deleted file mode 100644 index c0a07a4808..0000000000 --- a/docs/working/contributor_guide/environment_setup.md +++ /dev/null @@ -1 +0,0 @@ -# Setting up a development environment diff --git a/docs/working/examples/example_1.md b/docs/working/examples/example_1.md deleted file mode 100644 index d838c70c43..0000000000 --- a/docs/working/examples/example_1.md +++ /dev/null @@ -1 +0,0 @@ -# Example 1 diff --git a/docs/working/examples/example_2.md b/docs/working/examples/example_2.md deleted file mode 100644 index cbaa14d450..0000000000 --- a/docs/working/examples/example_2.md +++ /dev/null @@ -1 +0,0 @@ -# Example 2 diff --git a/docs/working/examples/example_3.md b/docs/working/examples/example_3.md deleted file mode 100644 index ee2b4b597a..0000000000 --- a/docs/working/examples/example_3.md +++ /dev/null @@ -1 +0,0 @@ -# Example 3 diff --git a/docs/working/faq/faq.md b/docs/working/faq/faq.md deleted file mode 100644 index 554f7bdbbc..0000000000 --- a/docs/working/faq/faq.md +++ /dev/null @@ -1 +0,0 @@ -# Frequently asked questions diff --git a/docs/working/getting_started/getting_started.md b/docs/working/getting_started/getting_started.md deleted file mode 100644 index 69a5d543e7..0000000000 --- a/docs/working/getting_started/getting_started.md +++ /dev/null @@ -1 +0,0 @@ -# Getting started diff --git a/docs/working/installation/install.md b/docs/working/installation/install.md deleted file mode 100644 index fed90cd40e..0000000000 --- a/docs/working/installation/install.md +++ /dev/null @@ -1 +0,0 @@ -# Install/Uninstall diff --git a/docs/working/introduction/introduction.md b/docs/working/introduction/introduction.md deleted file mode 100644 index e10b99d013..0000000000 --- a/docs/working/introduction/introduction.md +++ /dev/null @@ -1 +0,0 @@ -# Introduction diff --git a/docs/working/references/cli.md b/docs/working/references/cli.md deleted file mode 100644 index 69e4e8ddcc..0000000000 --- a/docs/working/references/cli.md +++ /dev/null @@ -1 +0,0 @@ -# Command line interface diff --git a/docs/working/references/configuration.md b/docs/working/references/configuration.md deleted file mode 100644 index a025a48b1b..0000000000 --- a/docs/working/references/configuration.md +++ /dev/null @@ -1 +0,0 @@ -# Configuration diff --git a/docs/working/references/porting_change_log.md b/docs/working/references/porting_change_log.md deleted file mode 100644 index b741e02012..0000000000 --- a/docs/working/references/porting_change_log.md +++ /dev/null @@ -1 +0,0 @@ -# Porting and change logs diff --git a/docs/working/references/road_map.md b/docs/working/references/road_map.md deleted file mode 100644 index e2b22830db..0000000000 --- a/docs/working/references/road_map.md +++ /dev/null @@ -1 +0,0 @@ -# Road map diff --git a/docs/working/user_guide/ci_integration.md b/docs/working/user_guide/ci_integration.md deleted file mode 100644 index 3819181114..0000000000 --- a/docs/working/user_guide/ci_integration.md +++ /dev/null @@ -1 +0,0 @@ -# CI/CD pipeline usage diff --git a/docs/working/user_guide/creating_testing_collection.md b/docs/working/user_guide/creating_testing_collection.md deleted file mode 100644 index 3d777722cd..0000000000 --- a/docs/working/user_guide/creating_testing_collection.md +++ /dev/null @@ -1 +0,0 @@ -# Creating and testing a collection diff --git a/docs/working/user_guide/testing_existing_collection.md b/docs/working/user_guide/testing_existing_collection.md deleted file mode 100644 index c2be9d28d0..0000000000 --- a/docs/working/user_guide/testing_existing_collection.md +++ /dev/null @@ -1 +0,0 @@ -# Testing an existing collection diff --git a/docs/working/user_guide/testing_existing_roles.md b/docs/working/user_guide/testing_existing_roles.md deleted file mode 100644 index 1d95dfe58f..0000000000 --- a/docs/working/user_guide/testing_existing_roles.md +++ /dev/null @@ -1 +0,0 @@ -# Testing existing roles diff --git a/docs/working/user_guide/understanding.md b/docs/working/user_guide/understanding.md deleted file mode 100644 index b6d94dca83..0000000000 --- a/docs/working/user_guide/understanding.md +++ /dev/null @@ -1 +0,0 @@ -# Understanding Molecule diff --git a/docs/working/user_guide/using_tox-ansible.md b/docs/working/user_guide/using_tox-ansible.md deleted file mode 100644 index b020c175a8..0000000000 --- a/docs/working/user_guide/using_tox-ansible.md +++ /dev/null @@ -1 +0,0 @@ -# Using tox-ansible diff --git a/mkdocs.yml b/mkdocs.yml index f000fc7ccb..b359899f6b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,49 +35,29 @@ 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 + - upgrade.md + - Getting Started Guide: getting-started.md + - User Guide: + - user_guide/understanding.md + - user_guide/testing_collections.md + - user_guide/testing_roles.md + - user_guide/ci.md + - user_guide/using_tox_ansible.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/porting_guide.md + - references/roadmap.md plugins: - autorefs