From bbfd6c6ab1239193242d6451280b987cc5e87426 Mon Sep 17 00:00:00 2001 From: Alicia Cozine Date: Fri, 20 Apr 2018 14:17:02 -0500 Subject: [PATCH] Internal refs (#39094) * fixes community refs * fixes appendix refs * fixes scenario refs, keeps ACI guide link to devel * fixes windows refs * fixes user guide refs * fixes dev guide refs --- .../rst/community/committer_guidelines.rst | 2 +- docs/docsite/rst/community/community.rst | 2 +- .../rst/community/development_process.rst | 2 +- docs/docsite/rst/community/how_can_I_help.rst | 2 +- .../rst/dev_guide/developing_modules.rst | 6 +++--- .../dev_guide/developing_modules_checklist.rst | 2 +- .../developing_modules_documenting.rst | 3 ++- .../dev_guide/developing_modules_in_groups.rst | 2 +- .../rst/dev_guide/developing_plugins.rst | 2 +- .../rst/dev_guide/style_guide/resources.rst | 18 ++++++------------ .../common_return_values.rst | 2 +- .../release_and_maintenance.rst | 4 +--- docs/docsite/rst/scenario_guides/guide_aci.rst | 2 +- .../rst/scenario_guides/guide_azure.rst | 2 +- .../rst/scenario_guides/guide_packet.rst | 2 +- .../docsite/rst/user_guide/modules_support.rst | 2 ++ .../docsite/rst/user_guide/playbooks_async.rst | 2 ++ docs/docsite/rst/user_guide/windows_dsc.rst | 2 +- docs/docsite/rst/user_guide/windows_faq.rst | 12 +++++++----- docs/docsite/rst/user_guide/windows_setup.rst | 2 +- docs/docsite/rst/user_guide/windows_usage.rst | 2 +- docs/docsite/rst/user_guide/windows_winrm.rst | 2 +- 22 files changed, 38 insertions(+), 39 deletions(-) diff --git a/docs/docsite/rst/community/committer_guidelines.rst b/docs/docsite/rst/community/committer_guidelines.rst index ea29572ea0c..3d1585ffe95 100644 --- a/docs/docsite/rst/community/committer_guidelines.rst +++ b/docs/docsite/rst/community/committer_guidelines.rst @@ -14,7 +14,7 @@ If you abuse the trust and break components and builds, etc., the trust level fa Features, High Level Design, and Roadmap ======================================== -As a core team member, you are an integral part of the team that develops the `roadmap `_. 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. +As a core team member, you are an integral part of the team that develops the :ref:`roadmap `. 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. diff --git a/docs/docsite/rst/community/community.rst b/docs/docsite/rst/community/community.rst index 5e33a3adfba..5a62d20a769 100644 --- a/docs/docsite/rst/community/community.rst +++ b/docs/docsite/rst/community/community.rst @@ -1,4 +1,4 @@ Community Information & Contributing ```````````````````````````````````` -This page is deprecated. Please see the updated `Ansible Community Guide `_. +This page is deprecated. Please see the updated :ref:`Ansible Community Guide `. diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 0cbb7de401c..9cebe5fe63e 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -10,7 +10,7 @@ This section discusses how the Ansible development and triage process works. Road Maps ========= -The Ansible Core team provides a road map for each upcoming release. These road maps can be found `here `_. +The Ansible Core team provides a road map for each upcoming release. These road maps can be found :ref:`here `. .. Roadmaps are User-oriented. We should also list the Roadmap Projects and the Blocker Bug Projects here diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst index e96be6ae5be..36023b7fa04 100644 --- a/docs/docsite/rst/community/how_can_I_help.rst +++ b/docs/docsite/rst/community/how_can_I_help.rst @@ -14,7 +14,7 @@ A great way to help the Ansible project is to become a power user: * Use Ansible everywhere you can * Take tutorials and classes -* Read the `official documentation `_ +* Read the :ref:`official documentation ` * Study some of the `many excellent books `_ about Ansible * `Get certified `_. diff --git a/docs/docsite/rst/dev_guide/developing_modules.rst b/docs/docsite/rst/dev_guide/developing_modules.rst index 7dbe227e635..df3cd0d8b85 100644 --- a/docs/docsite/rst/dev_guide/developing_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_modules.rst @@ -22,7 +22,7 @@ See :ref:`all_modules` for a list of existing modules. Modules can be written in any language and are found in the path specified by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or -in the `library section of the Ansible configuration file `_. +in the :envvar:`library section of the Ansible configuration file `. .. _module_dev_should_you: @@ -49,11 +49,11 @@ If you find an existing PR that looks like it addresses the issue you are trying Action plugins get run on the master instead of on the target. For modules like file/copy/template, some of the work needs to be done on the master before the module executes on the target. Action plugins execute first on the master and can then execute the normal module on the target if necessary. -For more information about action plugins, `read the action plugins documentation here `_. +For more information about action plugins, read the :ref:`action plugins documentation `. 4. Should you use a role instead? -Check out the roles documentation `available here `_. +Check out the :ref:`roles documentation`. 5. Should you write multiple modules instead of one module? diff --git a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst index da12a9623c3..e28f05fc52c 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst @@ -33,7 +33,7 @@ The following checklist items are important guidelines for people who want to c 'supported_by': 'community', 'metadata_version': '1.1'} -The complete module metadata specification is here: `Ansible metadata block `_ +Read the complete :ref:`module metadata specification ` for more information. * Documentation: Make sure it exists * Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance). diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 09b3bdb3676..5d497ae2159 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -67,6 +67,7 @@ add the newer line above the older one, like so: # Copyright: (c) 2015, [Original Contributor(s)] # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +.. _ansible_metadata_block: ANSIBLE_METADATA Block ---------------------- @@ -129,7 +130,7 @@ Fields certified instead) For information on what the support level values entail, please see - `Modules Support `_. + :ref:`Modules Support `. :status: This field records information about the module that is important to the end user. It's a list of strings. The default value diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst index 9cc70c446db..656e8fbac80 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -129,7 +129,7 @@ If there are multiple people that can be notified, please list them. That avoids **Review Module web docs** -Review the autogenerated module documentation for each of your modules, found in `Module Docs `_ to ensure they are correctly formatted. If there are any issues please fix by raising a single PR. +Review the autogenerated module documentation for each of your modules, found in :ref:`Module Docs ` to ensure they are correctly formatted. If there are any issues please fix by raising a single PR. If the module documentation hasn't been published live yet, please let a member of the Ansible Core Team know in the ``#ansible-devel`` IRC channel. diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 57c988a823e..e529316f4ec 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -279,7 +279,7 @@ The following is an example of how this lookup is called:: For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup `_. -For more usage examples of lookup plugins, see `Using Lookups `_. +For more usage examples of lookup plugins, see :ref:`Using Lookups`. .. _developing_vars_plugins: diff --git a/docs/docsite/rst/dev_guide/style_guide/resources.rst b/docs/docsite/rst/dev_guide/style_guide/resources.rst index 1cce66ed3d4..853af35f42d 100644 --- a/docs/docsite/rst/dev_guide/style_guide/resources.rst +++ b/docs/docsite/rst/dev_guide/style_guide/resources.rst @@ -1,16 +1,10 @@ Resources ```````````````` -Internal resources -------------------------- -- https://docs.ansible.com/ -- https://sites.google.com/a/ansibleworks.com/ansible-intranet/ -- ??? intranet Engineering doc??? +* Follow the style of the :ref:`Ansible Documentation` +* Ask for advice on IRC, on the ``#ansible-devel`` Freenode channel +* Review these online style guides: + * `AP Stylebook `_ + * `Chicago Manual of Style `_ + * `Strunk and White's Elements of Style `_ -External Resources -------------------------- -- https://www.apstylebook.com -- http://www.chicagomanualofstyle.org/home.html -- https://www.crockford.com/wrrrld/style.html -- http://orwell.ru -- http://www.computeruser.com diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index 638b6e8c158..6aee8fc6569 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -4,7 +4,7 @@ Return Values .. contents:: Topics Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by -the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and https://docs.ansible.com). +the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and on the :ref:`main docsite`. This document covers return values common to all modules. diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index ead713631da..9ab135195f1 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -29,11 +29,9 @@ latest features and security fixes. Older, unsupported versions of Ansible can contain unfixed security vulnerabilities (*CVE*). -You can refer to the `porting guides`_ for tips on updating your Ansible +You can refer to the :ref:`porting guides` for tips on updating your Ansible playbooks to run on newer versions. -.. _porting guides: https://docs.ansible.com/ansible/porting_guides.html - .. _release_schedule: Release status diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst index 08f1eab857e..5e9698cea62 100644 --- a/docs/docsite/rst/scenario_guides/guide_aci.rst +++ b/docs/docsite/rst/scenario_guides/guide_aci.rst @@ -65,7 +65,7 @@ For instance ensuring that a specific tenant exists, is done using the following description: Customer XYZ state: present -A complete list of existing ACI modules is available for `the latest stable release `_ as well as `the current development version `_. +A complete list of existing ACI modules is available for the latest stable release on the :ref:`list of network modules `. You can also view the `current development version `_. Querying ACI configuration .......................... diff --git a/docs/docsite/rst/scenario_guides/guide_azure.rst b/docs/docsite/rst/scenario_guides/guide_azure.rst index 5e1e8466261..90a96316443 100644 --- a/docs/docsite/rst/scenario_guides/guide_azure.rst +++ b/docs/docsite/rst/scenario_guides/guide_azure.rst @@ -238,7 +238,7 @@ virtual network already with an existing subnet, you can run the following to cr Dynamic Inventory Script ------------------------ -If you are not familiar with Ansible's dynamic inventory scripts, check out `Intro to Dynamic Inventory `_. +If you are not familiar with Ansible's dynamic inventory scripts, check out :ref:`Intro to Dynamic Inventory `. The Azure Resource Manager inventory script is called azure_rm.py. It authenticates with the Azure API exactly the same as the Azure modules, which means you will either define the same environment variables described above in `Using Environment Variables`_, diff --git a/docs/docsite/rst/scenario_guides/guide_packet.rst b/docs/docsite/rst/scenario_guides/guide_packet.rst index f394ac1e129..af275f3bd8a 100644 --- a/docs/docsite/rst/scenario_guides/guide_packet.rst +++ b/docs/docsite/rst/scenario_guides/guide_packet.rst @@ -10,7 +10,7 @@ Introduction - packet_sshkey: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys. - packet_device: manages servers on Packet. You can use this module to create, restart and delete devices. -Note, this guide assumes you are familiar with Ansible and how it works. If you're not, have a look at their `docs `_ before getting started. +Note, this guide assumes you are familiar with Ansible and how it works. If you're not, have a look at their :ref:`docs ` before getting started. Requirements ============ diff --git a/docs/docsite/rst/user_guide/modules_support.rst b/docs/docsite/rst/user_guide/modules_support.rst index 5f9d53ff226..161986b753b 100644 --- a/docs/docsite/rst/user_guide/modules_support.rst +++ b/docs/docsite/rst/user_guide/modules_support.rst @@ -1,3 +1,5 @@ +.. _modules_support: + Module Maintenance & Support ---------------------------- diff --git a/docs/docsite/rst/user_guide/playbooks_async.rst b/docs/docsite/rst/user_guide/playbooks_async.rst index dc46f78e969..a6a35ef97b5 100644 --- a/docs/docsite/rst/user_guide/playbooks_async.rst +++ b/docs/docsite/rst/user_guide/playbooks_async.rst @@ -1,3 +1,5 @@ +.. _playbooks_async: + Asynchronous Actions and Polling ================================ diff --git a/docs/docsite/rst/user_guide/windows_dsc.rst b/docs/docsite/rst/user_guide/windows_dsc.rst index bbbbe6230d4..2e0819ab998 100644 --- a/docs/docsite/rst/user_guide/windows_dsc.rst +++ b/docs/docsite/rst/user_guide/windows_dsc.rst @@ -387,7 +387,7 @@ Setup IIS Website An introduction to playbooks :doc:`playbooks_best_practices` Best practices advice - `List of Windows Modules `_ + `List of Windows Modules :ref:`` Windows specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/windows_faq.rst b/docs/docsite/rst/user_guide/windows_faq.rst index 69262de123c..828286e2fa2 100644 --- a/docs/docsite/rst/user_guide/windows_faq.rst +++ b/docs/docsite/rst/user_guide/windows_faq.rst @@ -6,7 +6,7 @@ their answers. .. note:: This document covers questions about managing Microsoft Windows servers with Ansible. For questions about Ansible Core, please see the - `FAQ page `_. + :ref:`FAQ page `. Does Ansible work with Windows XP or Server 2003? `````````````````````````````````````````````````` @@ -23,7 +23,7 @@ supported operating system versions are: * Windows 10 Ansible also has minimum PowerShell version requirements - please see -:doc:`windows_setup` for the lastest information. +:doc:`windows_setup` for the latest information. Can I Manage Windows Nano Server? ````````````````````````````````` @@ -70,6 +70,8 @@ The way that these certificates are generated and mapped to a user is different from the SSH implementation; consult the :doc:`windows_winrm` documentation for more information. +.. _windows_faq_winrm: + Why can I run a command locally that does not work under Ansible? ````````````````````````````````````````````````````````````````` Ansible executes commands through WinRM. These processes are different from @@ -110,7 +112,7 @@ See :doc:`become` more info on how to use become. The limitations section at This program won't install with Ansible ``````````````````````````````````````` -See `the question `_ for more information about WinRM limitations. +See :ref:`this question ` for more information about WinRM limitations. What modules are available? ``````````````````````````` @@ -119,8 +121,8 @@ Linux/Unix machines and arbitrary web services. These modules are written in Python and most of them do not work on Windows. Because of this, there are dedicated Windows modules that are written in -PowerShell and are meant to be run on Windows hosts. A list of this modules -can be found `here `_. +PowerShell and are meant to be run on Windows hosts. A list of these modules +can be found :ref:`here `. In addition, the following Ansible Core modules/action-plugins work with Windows: diff --git a/docs/docsite/rst/user_guide/windows_setup.rst b/docs/docsite/rst/user_guide/windows_setup.rst index bb741c93342..8bea549504e 100644 --- a/docs/docsite/rst/user_guide/windows_setup.rst +++ b/docs/docsite/rst/user_guide/windows_setup.rst @@ -447,7 +447,7 @@ Windows host. An introduction to playbooks :doc:`playbooks_best_practices` Best practices advice - `List of Windows Modules `_ + :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/windows_usage.rst b/docs/docsite/rst/user_guide/windows_usage.rst index 6516d8979ef..a6c31f225ed 100644 --- a/docs/docsite/rst/user_guide/windows_usage.rst +++ b/docs/docsite/rst/user_guide/windows_usage.rst @@ -483,7 +483,7 @@ guides for Windows modules differ substantially from those for standard standard An introduction to playbooks :doc:`playbooks_best_practices` Best practices advice - `List of Windows Modules `_ + :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/windows_winrm.rst b/docs/docsite/rst/user_guide/windows_winrm.rst index 0cd81eab327..7e9e807a3dc 100644 --- a/docs/docsite/rst/user_guide/windows_winrm.rst +++ b/docs/docsite/rst/user_guide/windows_winrm.rst @@ -767,7 +767,7 @@ Some of these limitations can be mitigated by doing one of the following: An introduction to playbooks :doc:`playbooks_best_practices` Best practices advice - `List of Windows Modules `_ + :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the google group!