From a48502138afc0c09d4db2c79a64cfa1453708429 Mon Sep 17 00:00:00 2001 From: Sorin Sbarnea Date: Tue, 7 Jul 2020 12:20:06 +0100 Subject: [PATCH] Documentation cleanup (#2736) --- .gitignore | 1 + AUTHORS.rst | 18 ---- CONTRIBUTING.rst | 137 ----------------------------- docs/authors.rst | 1 - docs/conf.py | 5 +- docs/contributing.rst | 200 +++++++++++++++++++++++++++++++++++++++++- docs/development.rst | 19 ---- docs/index.rst | 15 ++-- docs/testing.rst | 90 ------------------- docs/upgrade.rst | 7 -- tox.ini | 8 +- 11 files changed, 213 insertions(+), 288 deletions(-) delete mode 100644 AUTHORS.rst delete mode 100644 CONTRIBUTING.rst delete mode 100644 docs/authors.rst delete mode 100644 docs/development.rst delete mode 100644 docs/testing.rst delete mode 100644 docs/upgrade.rst diff --git a/.gitignore b/.gitignore index 5dd4b5f30..82ce98412 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ ubuntu-xenial-16.04-cloudimg-console.log .python-version coverage.xml pip-wheel-metadata +docs/docstree diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index d34cd29fd..000000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,18 +0,0 @@ -******* -Credits -******* - -Based on the good work of John Dewey (`@retr0h`_). - -.. _`@retr0h`: https://github.com/retr0h - -Contributors -============ - -Please see the following: - -* `Contributors listing`_ -* `Community working group members`_ - -.. _Contributors listing: https://github.com/ansible-community/molecule/graphs/contributors -.. _Community working group members: https://github.com/ansible/community/wiki/Molecule diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index f18d819e5..000000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,137 +0,0 @@ -************ -Contributing -************ - -Move to Red Hat -=============== - -.. important:: - - During the end of October 2018 the Molecule Project was moved to its new home - under Ansible by Red Hat. - -How to get involved -------------------- - -* To see what's planned see the `Molecule Project Board`_. -* Join the Molecule `community working group`_ if you would like to - influence the direction of the project. - -.. _community working group: https://github.com/ansible/community/wiki/molecule -.. _Molecule Project Board: https://github.com/ansible-community/molecule/projects - -New Docker location -------------------- - -For people that use the Docker image, we are now publishing to a new location `Molecule on quay.io`_. - -old location: ``https://hub.docker.com/r/retr0h/molecule/`` - -new location: ``https://quay.io/repository/ansible/molecule`` - -How to use:: - - docker pull quay.io/ansible/molecule:latest - -.. _`Molecule on quay.io`: https://quay.io/repository/ansible/molecule - - -Release announcements ---------------------- - -Want to know about releases, subscribe to `ansible-announce list`_ - -.. _`ansible-announce list`: https://groups.google.com/group/ansible-announce - -Talk to us ----------- - -Join us in ``#ansible-molecule`` on `freenode`_, or `molecule-users Forum`_. - -The full list of Ansible email lists and IRC channels can be found in the `communication page`_. - -.. _`freenode`: https://freenode.net -.. _`molecule-users Forum`: https://groups.google.com/forum/#!forum/molecule-users -.. _`communication page`: https://docs.ansible.com/ansible/latest/community/communication.html - -Contribution Guidelines -======================= - -* We are interested in various different kinds of improvement for Molecule; - please feel free to raise an `Issue`_ if you would like to work on something - major to ensure efficient collaboration and avoid duplicate effort. -* Create a topic branch from where you want to base your work. -* Check for unnecessary whitespace with ``git diff --check`` before committing. - Please see `formatting`_ and `linting`_ documentation for further commands. -* Make sure you have added tests for your changes. -* Although not required, it is good to sign off commits using ``git commit --signoff``, and agree - that usage of ``--signoff`` constitutes agreement with the terms of `DCO 1.1`_. - -* Run all the tests to ensure nothing else was accidentally broken. -* Reformat the code by following the formatting section below. -* Submit a pull request. - -.. _`Issue`: https://github.com/ansible-community/molecule/issues/new/choose -.. _`DCO 1.1`: https://github.com/ansible-community/molecule/blob/master/DCO_1_1.md -.. _formatting: https://molecule.readthedocs.io/en/latest/testing.html#formatting -.. _linting: https://molecule.readthedocs.io/en/latest/testing.html#linting - -Code Of Conduct -=============== - -Please see our `Code of Conduct`_ document. - -.. _Code of Conduct: https://github.com/ansible-community/molecule/blob/master/.github/CODE_OF_CONDUCT.md - -Pull Request Life Cycle and Governance -====================================== - -* If your PRs get stuck `join us on IRC`_ or add to the `working group agenda`_. -* The code style is what is enforced by CI, everything else is off topic. -* All PRs must be reviewed by one other person. This is enforced by GitHub. Larger changes require +2. - -.. _working group agenda: https://github.com/ansible/community/wiki/Molecule#meetings -.. _join us on IRC: https://github.com/ansible/community/wiki/Molecule#join-the-discussion - -Installing -========== - -:ref:`installation` from source or package. - -Testing -======= - -Please see :ref:`full_testing`. - -Documentation -============= - -Working with InterSphinx ------------------------- - -In the `conf.py`_, we define an ``intersphinx_mapping`` which provides the base -URLs for conveniently linking to other Sphinx documented projects. In order to -find the correct link syntax and text you can link to, you can quickly inspect -the reference from the command line. - -For example, if we would like to link to a specific part of the Ansible -documentation, we could first run the following command: - -.. code-block:: bash - - python -m sphinx.ext.intersphinx https://docs.ansible.com/ansible/latest/objects.inv - -And then see the entire Sphinx listing. We see entries that look like: - -.. code-block:: bash - - py:attribute - AnsibleModule._debug api/index.html#AnsibleModule._debug - -With which we can link out to using the following syntax: - -.. code-block:: bash - - :py:attribute:`AnsibleModule._debug` - -.. _conf.py: ../source/conf.py diff --git a/docs/authors.rst b/docs/authors.rst deleted file mode 100644 index e122f914a..000000000 --- a/docs/authors.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../AUTHORS.rst diff --git a/docs/conf.py b/docs/conf.py index 50f7033f4..e9d0f51ba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -153,13 +153,14 @@ "style_nav_header_background": "#5bbdbf", "style_external_links": True, # 'canonical_url': "https://docs.ansible.com/ansible/latest/", - 'vcs_pageview_mode': 'edit' + 'vcs_pageview_mode': 'edit', + "navigation_depth": 3, } html_context = { 'display_github': 'True', 'github_user': 'ansible-community', - 'github_repo': 'sphinx_ansible_theme', + 'github_repo': 'molecule', 'github_version': 'master/docs/', 'current_version': version, 'latest_version': 'latest', diff --git a/docs/contributing.rst b/docs/contributing.rst index 462818222..52680322a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,3 +1,201 @@ +.. toctree:: + :hidden: + .. _contributing: -.. include:: ../CONTRIBUTING.rst +************ +Contributing +************ + + +* To see what's planned see the `Molecule Project Board`_. +* Join the Molecule `community working group`_ if you would like to + influence the direction of the project. + +.. _community working group: https://github.com/ansible/community/wiki/molecule +.. _Molecule Project Board: https://github.com/ansible-community/molecule/projects + + +Talk to us +---------- + +Join us in ``#ansible-molecule`` on `freenode`_, or `molecule-users Forum`_. + +The full list of Ansible email lists and IRC channels can be found in the `communication page`_. + +.. _`freenode`: https://freenode.net +.. _`molecule-users Forum`: https://groups.google.com/forum/#!forum/molecule-users +.. _`communication page`: https://docs.ansible.com/ansible/latest/community/communication.html + +Guidelines +========== + +* We are interested in various different kinds of improvement for Molecule; + please feel free to raise an `Issue`_ if you would like to work on something + major to ensure efficient collaboration and avoid duplicate effort. +* Create a topic branch from where you want to base your work. +* Check for unnecessary whitespace with ``git diff --check`` before committing. + Please see `formatting`_ and `linting`_ documentation for further commands. +* Make sure you have added tests for your changes. +* Although not required, it is good to sign off commits using ``git commit --signoff``, and agree + that usage of ``--signoff`` constitutes agreement with the terms of `DCO 1.1`_. + +* Run all the tests to ensure nothing else was accidentally broken. +* Reformat the code by following the formatting section below. +* Submit a pull request. + +.. _`Issue`: https://github.com/ansible-community/molecule/issues/new/choose +.. _`DCO 1.1`: https://github.com/ansible-community/molecule/blob/master/DCO_1_1.md +.. _formatting: https://molecule.readthedocs.io/en/latest/testing.html#formatting +.. _linting: https://molecule.readthedocs.io/en/latest/testing.html#linting + +Code Of Conduct +=============== + +Please see our `Code of Conduct`_ document. + +.. _Code of Conduct: https://github.com/ansible-community/molecule/blob/master/.github/CODE_OF_CONDUCT.md + +Pull Request Life Cycle and Governance +====================================== + +* If your PRs get stuck `join us on IRC`_ or add to the `working group agenda`_. +* The code style is what is enforced by CI, everything else is off topic. +* All PRs must be reviewed by one other person. This is enforced by GitHub. Larger changes require +2. + +.. _working group agenda: https://github.com/ansible/community/wiki/Molecule#meetings +.. _join us on IRC: https://github.com/ansible/community/wiki/Molecule#join-the-discussion + +.. _testing: + +Testing +======= + +Molecule has an extensive set of unit and functional tests. Molecule uses +`Tox`_ factors to generate a matrix of python x Ansible x unit/functional +tests. Manual setup required as of this time. + +Dependencies +------------ + +Tests will be skipped when the driver's binary is not present. + +Install the test framework `Tox`_. + +.. code-block:: bash + + $ python3 -m pip install tox + +.. _Tox: https://tox.readthedocs.io/en/latest/ +.. _full_testing: + +Full +---- + +Run all tests, including linting and coverage reports. This should be run +prior to merging or submitting a pull request. + +.. code-block:: bash + + $ tox + +List available scenarios +------------------------ + +List all available scenarios. This is useful to target specific Python and +Ansible version for the functional and unit tests. + +.. code-block:: bash + + $ tox -av + +Unit +---- + +Run all unit tests with coverage. + +.. code-block:: bash + + $ tox -e 'py{27,35,36,37,38}-ansible{25,26,27,28}-unit' + +Run all unit tests for a specific version of Python and Ansible (here Python 3.7 +and Ansible 2.7). + +.. code-block:: bash + + $ tox -e py37-ansible28-unit + +Linting +------- + +Linting is performed by a combination of linters. + +Run all the linters (some perform changes to conform the code to the style rules). + +.. code-block:: bash + + $ tox -e lint + +Documentation +------------- + +Generate the documentation, using `sphinx`_. + +.. code-block:: bash + + $ tox -e docs + +.. _`sphinx`: http://www.sphinx-doc.org + +Build container images +---------------------- + +Build the container images with docker or podman. + +.. code-block:: bash + + $ tox -e build-containers + +Documentation +============= + +Working with InterSphinx +------------------------ + +In the `conf.py`_, we define an ``intersphinx_mapping`` which provides the base +URLs for conveniently linking to other Sphinx documented projects. In order to +find the correct link syntax and text you can link to, you can quickly inspect +the reference from the command line. + +For example, if we would like to link to a specific part of the Ansible +documentation, we could first run the following command: + +.. code-block:: bash + + python -m sphinx.ext.intersphinx https://docs.ansible.com/ansible/latest/objects.inv + +And then see the entire Sphinx listing. We see entries that look like: + +.. code-block:: bash + + py:attribute + AnsibleModule._debug api/index.html#AnsibleModule._debug + +With which we can link out to using the following syntax: + +.. code-block:: bash + + :py:attribute:`AnsibleModule._debug` + +.. _conf.py: ../source/conf.py + + +Credits +======= + +Based on the good work of John Dewey (`@retr0h`_) and other contributors_. +Active member list can be seen at `Molecule working group`_. + +.. _@retr0h: https://github.com/retr0h +.. _contributors: https://github.com/ansible-community/molecule/graphs/contributors +.. _Molecule working group: https://github.com/ansible/community/wiki/Molecule diff --git a/docs/development.rst b/docs/development.rst deleted file mode 100644 index 09921eecd..000000000 --- a/docs/development.rst +++ /dev/null @@ -1,19 +0,0 @@ -*********** -Development -*********** - -* Please read the :ref:`contributing` guidelines. - -Release -------- - -Molecule follows `Semantic Versioning`_. - -.. _`Semantic Versioning`: https://semver.org - -Docker Build -^^^^^^^^^^^^ - -* `Quay.io`_ automatically builds on commit and tag - -.. _`quay.io`: https://quay.io/repository/ansible/molecule diff --git a/docs/index.rst b/docs/index.rst index e569fad0e..34faa8e64 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,9 +7,7 @@ Installation and Upgrade .. toctree:: :maxdepth: 1 - Installation Guide - Upgrade Guide - Releases and changelogs + Installation Using Molecule ============== @@ -17,9 +15,10 @@ Using Molecule .. toctree:: :maxdepth: 1 - Getting Started Guide + Getting Started + CI/CD Usage Command Line Reference - Configuration Guide + Configuration Common Molecule Use Cases ========================= @@ -36,10 +35,8 @@ Contributing to Molecule .. toctree:: :maxdepth: 1 - Contribution Guide - Developer Testing Guide - Developer Release Guide - Credits + Contributing + References and Appendices ========================= diff --git a/docs/testing.rst b/docs/testing.rst deleted file mode 100644 index 5ccb905ef..000000000 --- a/docs/testing.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. _testing: - -Testing -======= - -Molecule has an extensive set of unit and functional tests. Molecule uses -`Tox`_ `Factors`_ to generate a matrix of python x Ansible x unit/functional -tests. Manual setup required as of this time. - -Dependencies ------------- - -Tests will be skipped when the driver's binary is not present. - -Install the test framework `Tox`_. - -.. code-block:: bash - - $ python3 -m pip install tox - -.. _full_testing: - -Full ----- - -Run all tests, including linting and coverage reports. This should be run -prior to merging or submitting a pull request. - -.. code-block:: bash - - $ tox - -List available scenarios ------------------------- - -List all available scenarios. This is useful to target specific Python and -Ansible version for the functional and unit tests. - -.. code-block:: bash - - $ tox -av - -Unit ----- - -Run all unit tests with coverage. - -.. code-block:: bash - - $ tox -e 'py{27,35,36,37,38}-ansible{25,26,27,28}-unit' - -Run all unit tests for a specific version of Python and Ansible (here Python 3.7 -and Ansible 2.7). - -.. code-block:: bash - - $ tox -e py37-ansible28-unit - -Linting -------- - -Linting is performed by a combination of linters. - -Run all the linters (some perform changes to conform the code to the style rules). - -.. code-block:: bash - - $ tox -e lint - -Documentation -------------- - -Generate the documentation, using `sphinx`_. - -.. code-block:: bash - - $ tox -e docs - -.. _`sphinx`: http://www.sphinx-doc.org - -Build container images ----------------------- - -Build the container images with docker or podman. - -.. code-block:: bash - - $ tox -e build-containers - -.. include:: ci.rst diff --git a/docs/upgrade.rst b/docs/upgrade.rst deleted file mode 100644 index 6a0023789..000000000 --- a/docs/upgrade.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _upgrade: - -************* -Upgrade Guide -************* - -TODO. diff --git a/tox.ini b/tox.ini index 0408da3f0..6c8e0b2ef 100644 --- a/tox.ini +++ b/tox.ini @@ -44,9 +44,9 @@ extras = podman test windows -commands_pre = - find {toxinidir} -type f -not -path '{toxinidir}/.tox/*' -path '*/__pycache__/*' -name '*.py[c|o]' -delete - sh -c 'find {homedir}/.cache -type d -path "*/molecule_*" -exec rm -rfv \{\} +;' +; commands_pre = +; find {toxinidir} -type f -not -path '{toxinidir}/.tox/*' -path '*/__pycache__/*' -name '*.py[c|o]' -delete +; sh -c 'find {homedir}/.cache -type d -path "*/molecule_*" -exec rm -rfv \{\} +;' commands = ansibledevel: ansible-galaxy install git+https://github.com/ansible-collections/community.general.git # failsafe as pip may install incompatible dependencies @@ -86,7 +86,7 @@ commands = # Print out the output docs dir and a way to serve html: python -c \ 'import pathlib; '\ - 'docs_dir = pathlib.Path(r"{toxinidir}") / "docs/html"; index_file = docs_dir / "index.html"; print(f"\nDocumentation available under `file://\{index_file\}`\n\nTo serve docs, use `python3 -m http.server --directory \{docs_dir\} 0`\n")' + 'docs_dir = pathlib.Path(r"{toxinidir}") / "docs/docstree/html"; index_file = docs_dir / "index.html"; print(f"\nDocumentation available under `file://\{index_file\}`\n\nTo serve docs, use `python3 -m http.server --directory \{docs_dir\} 0`\n")' extras = docs