Remove more docs build errors (#45364)
* orphans testing pages to avoid not-in-toctree errors * orphans various pages pending reorg * adds module_utils and special_vars to main TOC * uses a glob for scenario_guide TOC * normalize and Sentence-case headings on community pages, typos * re-orgs community TOC, adds all pages to toctree * removes scenario guides index page * adds style guide to community index * basic update to style guide * fix typo that created a new error * removes not-in-toctree from ignore errors list * leave removing files for future cleanup task
This commit is contained in:
Alicia Cozine
John R Barker
parent
600c7ac108
commit
4264be2b18
32 changed files with 179 additions and 160 deletions
|
|
@ -1,24 +1,25 @@
|
|||
.. _community_committer_guidelines:
|
||||
|
||||
Committers Guidelines (for people with commit rights to Ansible on GitHub)
|
||||
``````````````````````````````````````````````````````````````````````````
|
||||
*********************
|
||||
Committers Guidelines
|
||||
*********************
|
||||
|
||||
These are the guidelines for people with commit access to Ansible. Committers are essentially acting as members of the Ansible Core team, although not necessarily as an employee of Ansible and Red Hat. Please read the guidelines before you commit.
|
||||
These are the guidelines for people with commit privileges on the Ansible GitHub repository. Committers are essentially acting as members of the Ansible Core team, although not necessarily as employees of Ansible and Red Hat. Please read the guidelines before you commit.
|
||||
|
||||
These guidelines apply to everyone. At the same time, this ISN'T a process document. So just use good judgement. You've been given commit access because we trust your judgement.
|
||||
|
||||
That said, use the trust wisely.
|
||||
That said, use the trust wisely.
|
||||
|
||||
If you abuse the trust and break components and builds, etc., the trust level falls and you may be asked not to commit or you may lose access to do so.
|
||||
If you abuse the trust and break components and builds, etc., the trust level falls and you may be asked not to commit or you may lose your commit privileges.
|
||||
|
||||
Features, High Level Design, and Roadmap
|
||||
Features, high-level design, and roadmap
|
||||
========================================
|
||||
|
||||
As a core team member, you are an integral part of the team that develops the :ref:`roadmap <roadmaps>`. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, etc. for various releases. Red Hat, the company, and the Ansible team must get these committed features (etc.) completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it impacts a lot of other parts within Ansible.
|
||||
|
||||
Any other new features and changes to high level design should go through the proposal process (TBD), to ensure the community and core team have had a chance to review the idea and approve it. The core team has sole responsibility for merging new features based on proposals.
|
||||
|
||||
Our Workflow on GitHub
|
||||
Our workflow on GitHub
|
||||
======================
|
||||
|
||||
As a committer, you may already know this, but our workflow forms a lot of our team policies. Please ensure you're aware of the following workflow steps:
|
||||
|
|
@ -29,19 +30,19 @@ As a committer, you may already know this, but our workflow forms a lot of our t
|
|||
* Adjust code as necessary based on the Comments provided
|
||||
* Ask someone on the Core Team to do a final review and merge
|
||||
|
||||
Addendum to workflow for Committers:
|
||||
Addendum to workflow for committers:
|
||||
------------------------------------
|
||||
|
||||
The Core Team is aware that this can be a difficult process at times. Sometimes, the team breaks the rules: Direct commits, merging their own PRs. This section is a set of guidelines. If you're changing a comma in a doc, or making a very minor change, you can use your best judgement. This is another trust thing. The process is critical for any major change, but for little things or getting something done quickly, use your best judgement and make sure people on the team are aware of your work.
|
||||
The Core Team is aware that this can be a difficult process at times. Sometimes, the team breaks the rules by making direct commits or merging their own PRs. This section is a set of guidelines. If you're changing a comma in a doc, or making a very minor change, you can use your best judgement. This is another trust thing. The process is critical for any major change, but for little things or getting something done quickly, use your best judgement and make sure people on the team are aware of your work.
|
||||
|
||||
Roles on Core
|
||||
=============
|
||||
* Core Committers: Fine to do PRs for most things, but we should have a timebox. Hanging PRs may merge on the judgement of these devs.
|
||||
* Module Owners: Module Owners own specific modules and have indirect commit access via the current module PR mechanisms.
|
||||
* Core committers: Fine to do PRs for most things, but we should have a timebox. Hanging PRs may merge on the judgement of these devs.
|
||||
* :ref:`Module maintainers <maintainers>`: Module maintainers own specific modules and have indirect commit access via the current module PR mechanisms.
|
||||
|
||||
General Rules
|
||||
General rules
|
||||
=============
|
||||
Individuals with direct commit access to ansible/ansible are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgement.
|
||||
Individuals with direct commit access to ansible/ansible are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgement.
|
||||
|
||||
* Don't
|
||||
|
||||
|
|
@ -64,11 +65,12 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe
|
|||
- Consider scope, sometimes a fix can be generalized
|
||||
- Keep it simple, then things are maintainable, debuggable and intelligible.
|
||||
|
||||
Committers are expected to continue to follow the same community and contribution guidelines followed by the rest of the Ansible community.
|
||||
Committers are expected to continue to follow the same community and contribution guidelines followed by the rest of the Ansible community.
|
||||
|
||||
|
||||
People
|
||||
======
|
||||
|
||||
Individuals who've been asked to become a part of this group have generally been contributing in significant ways to the Ansible community for some time. Should they agree, they are requested to add their names and GitHub IDs to this file, in the section below, via a pull request. Doing so indicates that these individuals agree to act in the ways that their fellow committers trust that they will act.
|
||||
|
||||
+---------------------+----------------------+--------------------+----------------------+
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ Code of Conduct
|
|||
|
||||
Please read and understand the :ref:`code_of_conduct`.
|
||||
|
||||
Mailing List Information
|
||||
Mailing list information
|
||||
========================
|
||||
|
||||
Ansible has several mailing lists. Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear.
|
||||
|
|
@ -28,12 +28,12 @@ Ansible has several mailing lists. Your first post to the mailing list will be
|
|||
|
||||
To subscribe to a group from a non-Google account, you can send an email to the subscription address requesting the subscription. For example: `ansible-devel+subscribe@googlegroups.com`
|
||||
|
||||
IRC Channel
|
||||
===========
|
||||
IRC channels
|
||||
============
|
||||
|
||||
Ansible has several IRC channels on Freenode (irc.freenode.net).
|
||||
|
||||
General Channels
|
||||
General channels
|
||||
----------------
|
||||
|
||||
- ``#ansible`` - For general use questions and support.
|
||||
|
|
@ -41,8 +41,8 @@ General Channels
|
|||
- ``#ansible-meeting`` - For public community meetings. We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_
|
||||
- ``#ansible-notices`` - Mostly bot output from things like GitHub, etc.
|
||||
|
||||
Working Group
|
||||
-------------
|
||||
Working groups
|
||||
--------------
|
||||
|
||||
- ``#ansible-aws`` - For discussions on Amazon Web Services.
|
||||
- ``#ansible-community`` - Channel for discussing Ansible Community related things.
|
||||
|
|
@ -54,20 +54,20 @@ Working Group
|
|||
- ``#ansible-windows`` - For discussions on Ansible & Windows.
|
||||
|
||||
|
||||
Language specific channels
|
||||
Language-specific channels
|
||||
--------------------------
|
||||
|
||||
- ``#ansible-es`` - Channel for Spanish speaking Ansible community.
|
||||
- ``#ansible-fr`` - Channel for French speaking Ansible community.
|
||||
|
||||
|
||||
IRC Meetings
|
||||
IRC meetings
|
||||
------------
|
||||
|
||||
The Ansible community holds regular IRC meetings on various topics, and anyone who is interested is invited to
|
||||
participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
|
||||
|
||||
Tower Support Questions
|
||||
Tower support questions
|
||||
========================
|
||||
|
||||
Ansible `Tower <https://www.ansible.com/products/tower>`_ is a UI, Server, and REST endpoint for Ansible.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
.. _community_development_process:
|
||||
|
||||
*******************************
|
||||
The Ansible Development Process
|
||||
===============================
|
||||
*******************************
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
|
|
|
|||
|
|
@ -1,22 +1,23 @@
|
|||
*************
|
||||
GitHub Admins
|
||||
=============
|
||||
*************
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
GitHub Admins have more permissions on GitHub than normal contributors. There are
|
||||
GitHub Admins have more permissions on GitHub than normal contributors or even committers. There are
|
||||
a few responsibilities that come with that increased power.
|
||||
|
||||
|
||||
Add and Remove Committers
|
||||
-------------------------
|
||||
Adding and removing committers
|
||||
==============================
|
||||
|
||||
The Ansible Team will periodically review who is actively contributing to Ansible to grant or revoke
|
||||
contributors' ability to commit on their own. GitHub Admins are the people who have the power to
|
||||
actually manage the GitHub permissions.
|
||||
|
||||
|
||||
Change Branch Permissions for Release
|
||||
-------------------------------------
|
||||
Changing branch permissions for releases
|
||||
========================================
|
||||
|
||||
When we make releases we make people go through a :ref:`release_managers` to push commits to that
|
||||
branch. The GitHub admins are responsible for setting the branch so only the Release Manager can
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
How To Help
|
||||
===========
|
||||
***************
|
||||
How can I help?
|
||||
***************
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
|
|
@ -8,7 +9,7 @@ Thanks for being interested in helping the Ansible project!
|
|||
There are many ways to help the Ansible project...but first, please read and understand the :ref:`code_of_conduct`.
|
||||
|
||||
Become a power user
|
||||
-------------------
|
||||
===================
|
||||
|
||||
A great way to help the Ansible project is to become a power user:
|
||||
|
||||
|
|
@ -21,21 +22,21 @@ A great way to help the Ansible project is to become a power user:
|
|||
When you become a power user, your ability and opportunities to help the Ansible project in other ways will multiply quickly.
|
||||
|
||||
Ask and answer questions online
|
||||
-------------------------------
|
||||
===============================
|
||||
|
||||
There are many forums online where Ansible users ask and answer questions. Reach out and communicate with your fellow Ansible users.
|
||||
|
||||
You can find the official :ref:`Ansible communication channels <communication>`.
|
||||
|
||||
Participate in your local meetup
|
||||
--------------------------------
|
||||
================================
|
||||
|
||||
There are Ansible meetups `all over the world <https://www.meetup.com/topics/ansible/>`_. Join your local meetup. Attend regularly. Ask good questions. Volunteer to give a presentation about how you use Ansible.
|
||||
|
||||
If there isn't a meetup near you, we'll be happy to help you `start one <https://www.ansible.com/community/events/ansible-meetups>`_.
|
||||
|
||||
File and verify issues
|
||||
----------------------
|
||||
======================
|
||||
|
||||
All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by :ref:`telling us about it <reporting_bugs_and_features>`.
|
||||
|
||||
|
|
@ -43,31 +44,31 @@ All software has bugs, and Ansible is no exception. When you find a bug, you can
|
|||
If you should discover that the bug you're trying to file already exists in an issue, you can help by verifying the behavior of the reported bug with a comment in that issue, or by reporting any additional information.
|
||||
|
||||
Review and submit pull requests
|
||||
-------------------------------
|
||||
===============================
|
||||
|
||||
As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you've got a solution to a bug you've found in Ansible, or if you've got a new feature that you've written and would like to share with millions of Ansible users, read all about the :ref:`Ansible development process <community_development_process>` to learn how to get your code accepted into Ansible.
|
||||
|
||||
Another good way to help is to review pull requests that other Ansible users have submitted. The Ansible community keeps a full list of `open pull requests by file <https://ansible.sivel.net/pr/byfile.html>`_, so if there's a particular module or plug-in that particularly interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback.
|
||||
|
||||
Become a module maintainer
|
||||
--------------------------
|
||||
==========================
|
||||
|
||||
Once you've learned about the development process and have contributed code to a particular module, we encourage you to become a maintainer of that module. There are hundreds of different modules in Ansible, and the vast majority of them are written and maintained entirely by members of the Ansible community.
|
||||
|
||||
To learn more about the responsibilities of being an Ansible module maintainer, please read our :ref:`module maintainer guidelines <maintainers>`.
|
||||
|
||||
Join a working group
|
||||
--------------------
|
||||
====================
|
||||
|
||||
Working groups are a way for Ansible community members to self-organize around particular topics of interest. We have working groups around various topics. To join or create a working group, please read the `Ansible working group guidelines <https://github.com/ansible/community/blob/master/WORKING-GROUPS.md>`_.
|
||||
|
||||
|
||||
Teach Ansible to others
|
||||
-----------------------
|
||||
=======================
|
||||
|
||||
We're working on a standardized Ansible workshop called `Lightbulb <https://github.com/ansible/lightbulb>`_ that can provide a good hands-on introduction to Ansible usage and concepts.
|
||||
|
||||
Social media
|
||||
------------
|
||||
============
|
||||
|
||||
If you like Ansible and just want to spread the good word, feel free to share on your social media platform of choice, and let us know by using ``@ansible`` or ``#ansible``. We'll be looking for you.
|
||||
|
|
|
|||
|
|
@ -10,19 +10,23 @@ The purpose of this guide is to teach you everything you need to know about bein
|
|||
|
||||
To get started, please read and understand the :ref:`code_of_conduct`, and then select one of the following topics.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
code_of_conduct
|
||||
development_process
|
||||
reporting_bugs_and_features
|
||||
how_can_I_help
|
||||
reporting_bugs_and_features
|
||||
communication
|
||||
development_process
|
||||
triage_process
|
||||
other_tools_and_programs
|
||||
../dev_guide/style_guide/index
|
||||
|
||||
.. toctree::
|
||||
:caption: Guidelines for specific types of contributors
|
||||
:maxdepth: 2
|
||||
|
||||
committer_guidelines
|
||||
maintainers
|
||||
release_managers
|
||||
communication
|
||||
other_tools_and_programs
|
||||
|
||||
|
||||
|
||||
|
||||
github_admins
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ In addition to the information below, module maintainers should be familiar with
|
|||
* Documentation on :ref:`module development <developing_modules>`
|
||||
|
||||
|
||||
Maintainer Responsibilities
|
||||
Maintainer responsibilities
|
||||
===========================
|
||||
|
||||
When you contribute a new module to the `ansible/ansible <https://github.com/ansible/ansible>`_ repository, you become the maintainer for that module once it has been merged. Maintainership empowers you with the authority to accept, reject, or request revisions to pull requests on your module -- but as they say, "with great power comes great responsibility."
|
||||
|
|
@ -27,10 +27,10 @@ Finally, following the `ansible-devel <https://groups.google.com/forum/#!forum/a
|
|||
|
||||
The Ansible community hopes that you will find that maintaining your module is as rewarding for you as having the module is for the wider community.
|
||||
|
||||
Pull Requests, Issues, and Workflow
|
||||
Pull requests, issues, and workflow
|
||||
===================================
|
||||
|
||||
Pull Requests
|
||||
Pull requests
|
||||
-------------
|
||||
|
||||
Module pull requests are located in the `main Ansible repository <https://github.com/ansible/ansible/pulls>`_.
|
||||
|
|
@ -44,7 +44,7 @@ Issues for modules, including bug reports, documentation bug reports, and featur
|
|||
|
||||
Issues for modules are routed to their maintainers via an automated process. This process is still being refined, and currently depends upon the issue creator to provide adequate details (specifically, providing the proper module name) in order to route it correctly. If you are a maintainer of a specific module, it is recommended that you periodically search module issues for issues which mention your module's name (or some variation on that name), as well as setting an appropriate notification process for receiving notification of mentions of your GitHub ID.
|
||||
|
||||
PR Workflow
|
||||
PR workflow
|
||||
-----------
|
||||
|
||||
Automated routing of pull requests is handled by a tool called `Ansibot <https://github.com/ansible/ansibullbot>`_.
|
||||
|
|
@ -58,8 +58,8 @@ Maintainers (BOTMETA.yml)
|
|||
|
||||
The full list of maintainers is located in `BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_.
|
||||
|
||||
Changing Maintainership
|
||||
-----------------------
|
||||
Adding and removing maintainers
|
||||
===============================
|
||||
|
||||
Communities change over time, and no one maintains a module forever. If you'd like to propose an additional maintainer for your module, please submit a PR to ``BOTMETA.yml`` with the GitHub username of the new maintainer.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,23 +1,22 @@
|
|||
.. _release_managers:
|
||||
|
||||
|
||||
Release Managers
|
||||
================
|
||||
**************************
|
||||
Release manager guidelines
|
||||
**************************
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
The release manager's purpose is to ensure a smooth release. To achieve that goal, they need to
|
||||
coordinate between:
|
||||
|
||||
* Developers with Commit privileges on the `Ansible github repository <https://github.com/ansible/ansible/>`_
|
||||
* Developers with commit privileges on the `Ansible GitHub repository <https://github.com/ansible/ansible/>`_
|
||||
* Contributors without commit privileges
|
||||
* The community
|
||||
* Ansible documentation team
|
||||
* Ansible Tower team
|
||||
|
||||
|
||||
Pre-releases: What and Why
|
||||
--------------------------
|
||||
Pre-releases: what and why
|
||||
==========================
|
||||
|
||||
Pre-releases exist to draw testers. They give people who don't feel comfortable running from source
|
||||
control a means to get an early version of the code to test and give us feedback. To ensure we get
|
||||
|
|
@ -35,18 +34,18 @@ back those changes to give people time to test between. People cannot test what
|
|||
we have to get those tarballs out there even if people feel they have to install more frequently.
|
||||
|
||||
|
||||
What is Beta?
|
||||
~~~~~~~~~~~~~
|
||||
Beta releases
|
||||
-------------
|
||||
|
||||
In a Beta release, we know there are still bugs. We will continue to accept fixes for these.
|
||||
In a beta release, we know there are still bugs. We will continue to accept fixes for these.
|
||||
Although we review these fixes, sometimes they can be invasive or potentially destabilize other
|
||||
areas of the code.
|
||||
|
||||
During the beta, we will no longer accept feature submissions.
|
||||
|
||||
|
||||
What is a Release Candidate?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Release candidates
|
||||
------------------
|
||||
|
||||
In a release candidate, we've fixed all known blockers. Any remaining bugfixes are
|
||||
ones that we are willing to leave out of the release. At this point we need user testing to
|
||||
|
|
@ -74,8 +73,8 @@ The last RC should be as close to the final as possible. The following things ma
|
|||
(like the Tower Team) which would want to test the code.
|
||||
|
||||
|
||||
Release Process
|
||||
===============
|
||||
Ansible release process
|
||||
=======================
|
||||
|
||||
The release process is kept in a `separate document
|
||||
<https://docs.google.com/document/d/10EWLkMesi9s_CK_GmbZlE_ZLhuQr6TBrdMLKo5dnMAI/edit#heading=h.ooo3izcel3cz>`_
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Reporting Bugs And Requesting Features
|
|||
|
||||
.. contents:: Topics
|
||||
|
||||
Reporting A Bug
|
||||
Reporting a bug
|
||||
===============
|
||||
|
||||
Ansible practices responsible disclosure - if this is a security related bug, email `security@ansible.com <mailto:security@ansible.com>`_ instead of filing a ticket or posting to the Google Group and you will receive a prompt response.
|
||||
|
|
|
|||
|
|
@ -3,29 +3,29 @@
|
|||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
====================================
|
||||
*******************
|
||||
Ansible Style Guide
|
||||
====================================
|
||||
*******************
|
||||
|
||||
.. Welcome to Ansible Style Guide's documentation! ===============================================
|
||||
Welcome to the Ansible Style Guide
|
||||
==================================
|
||||
|
||||
Follow these guidelines to create clear, concise, useful community contributions and documentation. This guide helps us make the content on ansible.com consistent.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:numbered:
|
||||
|
||||
self
|
||||
why_use
|
||||
resources
|
||||
basic_rules
|
||||
voice_style
|
||||
trademarks
|
||||
grammar_punctuation
|
||||
spelling_word_choice
|
||||
|
||||
spelling_word_choice
|
||||
resources
|
||||
|
||||
.. Indices and tables
|
||||
.. ==================
|
||||
|
||||
.. * :ref:`genindex`
|
||||
.. * :ref:`modindex`
|
||||
.. Indices and tables
|
||||
.. ==================
|
||||
|
||||
.. * :ref:`genindex`
|
||||
.. * :ref:`modindex`
|
||||
.. * :ref:`search`
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
Why Use a Style Guide?
|
||||
`````````````````````````````````
|
||||
|
||||
|
|
@ -15,7 +17,7 @@ This style guide incorporates current Ansible resources and information so that
|
|||
|
||||
"If you don't find it in the index, look very carefully through the entire catalogue."
|
||||
― Sears, Roebuck and Co., 1897 Sears Roebuck & Co. Catalogue
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</blockquote>
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.. orphan:
|
||||
:orphan:
|
||||
|
||||
Sanity Tests » ansible-var-precedence-check
|
||||
===========================================
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.. orphan:
|
||||
:orphan:
|
||||
|
||||
Sanity Tests » docs-build
|
||||
=========================
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.. orphan:
|
||||
:orphan:
|
||||
|
||||
Sanity Tests » no-wildcard-import
|
||||
=================================
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.. orphan:
|
||||
:orphan:
|
||||
|
||||
Sanity Tests » pylint-ansible-test
|
||||
==================================
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_compile:
|
||||
|
||||
*************
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_documentation:
|
||||
|
||||
*********************
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
**********
|
||||
httptester
|
||||
**********
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_integration:
|
||||
|
||||
*****************
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_pep8:
|
||||
|
||||
*****
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_running_locally:
|
||||
|
||||
***************
|
||||
|
|
@ -40,13 +42,13 @@ Environment Variables
|
|||
|
||||
When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are:
|
||||
|
||||
* Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options.
|
||||
* Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options.
|
||||
* Not exposed to the test environment unless whitelisted in ``test/runner/lib/util.py`` in the ``common_environment`` function.
|
||||
* Not exposed to the test environment when using the ``--tox`` option unless whitelisted in ``test/runner/tox.ini`` by the ``passenv`` definition.
|
||||
|
||||
Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --tox``. However, using the ``--docker`` option would
|
||||
require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set
|
||||
and the tests executed. This is useful for debugging tests inside a container by following the
|
||||
Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --tox``. However, using the ``--docker`` option would
|
||||
require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set
|
||||
and the tests executed. This is useful for debugging tests inside a container by following the
|
||||
:ref:`Debugging AnsibleModule-based modules <debugging_ansiblemodule_based_modules>` instructions.
|
||||
|
||||
Interactive Shell
|
||||
|
|
@ -84,4 +86,3 @@ Reports can be generated in several different formats:
|
|||
To clear data between test runs, use the ``ansible-test coverage erase`` command. For a full list of features see the online help::
|
||||
|
||||
ansible-test coverage --help
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_sanity:
|
||||
|
||||
************
|
||||
|
|
@ -75,5 +77,3 @@ yamllint
|
|||
~~~~~~~~
|
||||
|
||||
Check YAML files for syntax and formatting issues.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_units:
|
||||
|
||||
**********
|
||||
|
|
@ -91,7 +93,7 @@ Structuring Unit Tests
|
|||
|
||||
Ansible drives unit tests through `pytest <https://docs.pytest.org/en/latest/>`_. This
|
||||
means that tests can either be written a simple functions which are included in any file
|
||||
name like ``test_<something>.py`` or as classes.
|
||||
name like ``test_<something>.py`` or as classes.
|
||||
|
||||
Here is an example of a function::
|
||||
|
||||
|
|
@ -102,23 +104,23 @@ Here is an example of a function::
|
|||
b = 23
|
||||
c = 33
|
||||
assert a + b = c
|
||||
|
||||
|
||||
Here is an example of a class::
|
||||
|
||||
import unittest
|
||||
|
||||
|
||||
class AddTester(unittest.TestCase)
|
||||
|
||||
|
||||
def SetUp()
|
||||
self.a = 10
|
||||
self.b = 23
|
||||
|
||||
# this function will
|
||||
|
||||
# this function will
|
||||
def test_add()
|
||||
c = 33
|
||||
assert self.a + self.b = c
|
||||
|
||||
# this function will
|
||||
# this function will
|
||||
def test_subtract()
|
||||
c = -13
|
||||
assert self.a - self.b = c
|
||||
|
|
@ -127,7 +129,7 @@ Both methods work fine in most circumstances; the function-based interface is si
|
|||
quicker and so that's probably where you should start when you are just trying to add a
|
||||
few basic tests for a module. The class-based test allows more tidy set up and tear down
|
||||
of pre-requisites, so if you have many test cases for your module you may want to refactor
|
||||
to use that.
|
||||
to use that.
|
||||
|
||||
Assertions using the simple ``assert`` function inside the tests will give full
|
||||
information on the cause of the failure with a trace-back of functions called during the
|
||||
|
|
@ -202,9 +204,8 @@ reports.
|
|||
:doc:`testing_running_locally`
|
||||
Running tests locally including gathering and reporting coverage data
|
||||
`Python 3 documentation - 26.4. unittest — Unit testing framework <https://docs.python.org/3/library/unittest.html>`_
|
||||
The documentation of the unittest framework in python 3
|
||||
The documentation of the unittest framework in python 3
|
||||
`Python 2 documentation - 25.3. unittest — Unit testing framework <https://docs.python.org/3/library/unittest.html>`_
|
||||
The documentation of the earliest supported unittest framework - from Python 2.6
|
||||
`pytest: helps you write better programs <https://docs.pytest.org/en/latest/>`_
|
||||
The documentation of pytest - the framework actually used to run Ansible unit tests
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _testing_units_modules:
|
||||
|
||||
****************************
|
||||
|
|
@ -15,7 +17,7 @@ This document explains why, how and when you should use unit tests for Ansible m
|
|||
The document doesn't apply to other parts of Ansible for which the recommendations are
|
||||
normally closer to the Python standard. There is basic documentation for Ansible unit
|
||||
tests in the developer guide :doc:`testing_units`. This document should
|
||||
be readable for a new Ansible module author. If you find it incomplete or confusing,
|
||||
be readable for a new Ansible module author. If you find it incomplete or confusing,
|
||||
please open a bug or ask for help on Ansible IRC.
|
||||
|
||||
What Are Unit Tests?
|
||||
|
|
@ -69,10 +71,10 @@ When To Use Unit Tests
|
|||
There are a number of situations where unit tests are a better choice than integration
|
||||
tests. For example, testing things which are impossible, slow or very difficult to test
|
||||
with integration tests, such as:
|
||||
|
||||
|
||||
* Forcing rare / strange / random situations that can't be forced, such as specific network
|
||||
failures and exceptions
|
||||
* Extensive testing of slow configuration APIs
|
||||
* Extensive testing of slow configuration APIs
|
||||
* Situations where the integration tests cannot be run as part of the main Ansible
|
||||
continuous integraiton running in Shippable.
|
||||
|
||||
|
|
@ -92,11 +94,11 @@ creating a unit test when bug fixing a module, even if those tests do not often
|
|||
problems later. As a basic goal, every module should have at least one unit test which
|
||||
will give quick feedback in easy cases without having to wait for the integration tests to
|
||||
complete.
|
||||
|
||||
|
||||
Ensuring correct use of external interfaces
|
||||
-------------------------------------------
|
||||
|
||||
Unit tests can check the way in which external services are run to ensure that they match
|
||||
Unit tests can check the way in which external services are run to ensure that they match
|
||||
specifications or are as efficient as possible *even when the final output will not be changed*.
|
||||
|
||||
Example:
|
||||
|
|
@ -113,12 +115,12 @@ which checks that the call happens properly for the old version can help avoid t
|
|||
problem. In this situation it is very important to include version numbering in the test case
|
||||
name (see `Naming unit tests`_ below).
|
||||
|
||||
Providing specific design tests
|
||||
Providing specific design tests
|
||||
--------------------------------
|
||||
|
||||
By building a requirement for a particular part of the
|
||||
code and then coding to that requirement, unit tests _can_ sometimes improve the code and
|
||||
help future developers understand that code.
|
||||
help future developers understand that code.
|
||||
|
||||
Unit tests that test internal implementation details of code, on the other hand, almost
|
||||
always do more harm than good. Testing that your packages to install are stored in a list
|
||||
|
|
@ -126,7 +128,7 @@ would slow down and confuse a future developer who might need to change that lis
|
|||
dictionary for efficiency. This problem can be reduced somewhat with clear test naming so
|
||||
that the future developer immediately knows to delete the test case, but it is often
|
||||
better to simply leave out the test case altogether and test for a real valuable feature
|
||||
of the code, such as installing all of the packages supplied as arguments to the module.
|
||||
of the code, such as installing all of the packages supplied as arguments to the module.
|
||||
|
||||
|
||||
How to unit test Ansible modules
|
||||
|
|
@ -148,7 +150,7 @@ If a unit test is designed to verify compatibility with a specific software or A
|
|||
then include the version in the name of the unit test.
|
||||
|
||||
As an example, ``test_v2_state_present_should_call_create_server_with_name()`` would be a
|
||||
good name, ``test_create_server()`` would not be.
|
||||
good name, ``test_create_server()`` would not be.
|
||||
|
||||
|
||||
Use of Mocks
|
||||
|
|
@ -164,16 +166,16 @@ Ensuring failure cases are visible with mock objects
|
|||
----------------------------------------------------
|
||||
|
||||
Functions like :meth:`module.fail_json` are normally expected to terminate execution. When you
|
||||
run with a mock module object this doesn't happen since the mock always returns another mock
|
||||
run with a mock module object this doesn't happen since the mock always returns another mock
|
||||
from a function call. You can set up the mock to raise an exception as shown above, or you can
|
||||
assert that these functions have not been called in each test. For example::
|
||||
|
||||
module = MagicMock()
|
||||
function_to_test(module, argument)
|
||||
module.fail_json.assert_not_called()
|
||||
module.fail_json.assert_not_called()
|
||||
|
||||
This applies not only to calling the main module but almost any other
|
||||
function in a module which gets the module object.
|
||||
function in a module which gets the module object.
|
||||
|
||||
|
||||
Mocking of the actual module
|
||||
|
|
@ -193,9 +195,9 @@ above, either by throwing an exception or ensuring that they haven't been called
|
|||
module.exit_json.side_effect = AnsibleExitJson(Exception)
|
||||
with self.assertRaises(AnsibleExitJson) as result:
|
||||
return = my_module.test_this_function(module, argument)
|
||||
module.fail_json.assert_not_called()
|
||||
module.fail_json.assert_not_called()
|
||||
assert return["changed"] == True
|
||||
|
||||
|
||||
API definition with unit test cases
|
||||
-----------------------------------
|
||||
|
||||
|
|
@ -237,7 +239,7 @@ This is then used to create a list of states::
|
|||
simple_instance_list('available', {}),
|
||||
simple_instance_list('available', {}),
|
||||
]
|
||||
|
||||
|
||||
These states are then used as returns from a mock object to ensure that the ``await`` function
|
||||
waits through all of the states that would mean the RDS instance has not yet completed
|
||||
configuration::
|
||||
|
|
@ -269,10 +271,10 @@ The most common are documented below, and suggestions for others can be found by
|
|||
at the source code of the existing unit tests or asking on the Ansible IRC channel or mailing
|
||||
lists.
|
||||
|
||||
Module argument processing
|
||||
Module argument processing
|
||||
--------------------------
|
||||
|
||||
There are two problems with running the main function of a module:
|
||||
There are two problems with running the main function of a module:
|
||||
|
||||
* Since the module is supposed to accept arguments on ``STDIN`` it is a bit difficult to
|
||||
set up the arguments correctly so that the module will get them as parameters.
|
||||
|
|
@ -383,7 +385,7 @@ A Complete Example
|
|||
|
||||
The following example is a complete skeleton that reuses the mocks explained above and adds a new
|
||||
mock for :meth:`Ansible.get_bin_path`::
|
||||
|
||||
|
||||
import json
|
||||
|
||||
from ansible.compat.tests import unittest
|
||||
|
|
@ -546,7 +548,7 @@ the code in Ansible to trigger that failure.
|
|||
:doc:`developing_modules`
|
||||
How to develop modules
|
||||
`Python 3 documentation - 26.4. unittest — Unit testing framework <https://docs.python.org/3/library/unittest.html>`_
|
||||
The documentation of the unittest framework in python 3
|
||||
The documentation of the unittest framework in python 3
|
||||
`Python 2 documentation - 25.3. unittest — Unit testing framework <https://docs.python.org/3/library/unittest.html>`_
|
||||
The documentation of the earliest supported unittest framework - from Python 2.6
|
||||
`pytest: helps you write better programs <https://docs.pytest.org/en/latest/>`_
|
||||
|
|
@ -560,5 +562,5 @@ the code in Ansible to trigger that failure.
|
|||
Extreme Programming (XP), Clean Coding. Uncle Bob talks through how to benfit from this
|
||||
`"Why Most Unit Testing is Waste" https://rbcs-us.com/documents/Why-Most-Unit-Testing-is-Waste.pdf`
|
||||
An article warning against the costs of unit testing
|
||||
`'A Response to "Why Most Unit Testing is Waste"' https://henrikwarne.com/2014/09/04/a-response-to-why-most-unit-testing-is-waste/`
|
||||
`'A Response to "Why Most Unit Testing is Waste"' https://henrikwarne.com/2014/09/04/a-response-to-why-most-unit-testing-is-waste/`
|
||||
An response pointing to how to maintain the value of unit tests
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
****************
|
||||
validate-modules
|
||||
****************
|
||||
|
|
|
|||
|
|
@ -47,20 +47,10 @@ Ansible releases a new major release of Ansible approximately every two months.
|
|||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
:caption: Scenario Guides
|
||||
|
||||
scenario_guides/guide_aci
|
||||
scenario_guides/guide_aws
|
||||
scenario_guides/guide_azure
|
||||
scenario_guides/guide_cloudstack
|
||||
scenario_guides/guide_docker
|
||||
scenario_guides/guide_gce
|
||||
scenario_guides/guide_meraki
|
||||
scenario_guides/guide_packet
|
||||
scenario_guides/guide_rax
|
||||
scenario_guides/guide_rolling_upgrade
|
||||
scenario_guides/guide_vagrant
|
||||
scenario_guides/guide_vultr
|
||||
scenario_guides/guide_*
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
@ -75,7 +65,7 @@ Ansible releases a new major release of Ansible approximately every two months.
|
|||
network/index
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
:caption: Reference & Appendices
|
||||
|
||||
../modules/modules_by_category
|
||||
|
|
@ -90,6 +80,8 @@ Ansible releases a new major release of Ansible approximately every two months.
|
|||
dev_guide/testing/sanity/index
|
||||
reference_appendices/faq
|
||||
reference_appendices/glossary
|
||||
reference_appendices/module_utils
|
||||
reference_appendices/special_variables
|
||||
reference_appendices/tower
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
.. _implicit_localhost:
|
||||
|
||||
Implicit 'localhost'
|
||||
|
|
|
|||
|
|
@ -1,22 +1,15 @@
|
|||
Detailed Guides
|
||||
```````````````
|
||||
:orphan:
|
||||
|
||||
This section is new and evolving. The idea here is to explore particular use cases in greater depth and provide a more "top down" explanation of some basic features.
|
||||
***************
|
||||
Scenario Guides
|
||||
***************
|
||||
|
||||
The guides in this section explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features.
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
guide_aci
|
||||
guide_aws
|
||||
guide_azure
|
||||
guide_meraki
|
||||
guide_rax
|
||||
guide_gce
|
||||
guide_cloudstack
|
||||
guide_vagrant
|
||||
guide_rolling_upgrade
|
||||
guide_docker
|
||||
guide_packet
|
||||
guide_vultr
|
||||
guide_*
|
||||
|
||||
Pending topics may include: Docker, Jenkins, Google Compute Engine, Linode/DigitalOcean, Continuous Deployment, and more.
|
||||
Pending topics may include: Jenkins, Linode/DigitalOcean, Continuous Deployment, and more.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,10 @@
|
|||
:orphan:
|
||||
|
||||
.. _module_defaults_config:
|
||||
|
||||
*****************************
|
||||
Module Defaults Configuration
|
||||
=============================
|
||||
*****************************
|
||||
|
||||
Ansible 2.7 adds a preview-status feature to group together modules that share common sets of parameters. This makes
|
||||
it easier to author playbooks making heavy use of API-based modules such as cloud modules. By default Ansible ships
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
=======================
|
||||
:orphan:
|
||||
|
||||
***********************
|
||||
Search paths in Ansible
|
||||
=======================
|
||||
***********************
|
||||
|
||||
Absolute paths are not an issue as they always have a known start, but relative paths ... well, they are relative.
|
||||
|
||||
|
|
@ -32,7 +34,7 @@ i.e ::
|
|||
|
||||
The current working directory (cwd) is not searched. If you see it, it just happens to coincide with one of the paths above.
|
||||
If you `include` a task file from a role, it will NOT trigger role behavior, this only happens when running as a role, `include_role` will work.
|
||||
A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens.
|
||||
A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens.
|
||||
|
||||
As for includes, they try the path of the included file first and fall back to the play/role that includes them.
|
||||
|
||||
|
|
|
|||
|
|
@ -38,7 +38,6 @@ def main():
|
|||
|
||||
ignore_codes = [
|
||||
'reference-target-not-found',
|
||||
'not-in-toc-tree',
|
||||
]
|
||||
|
||||
used_ignore_codes = set()
|
||||
|
|
|
|||
Loading…
Reference in a new issue