address broken links in dev and appendices sections (#2402)

samccann · Akasurde · oraNod · web-flow · commit 7082b5ded583 · 2025-02-24T17:14:23.000Z
* fix some broken links

* malformed link

* Update docs/docsite/rst/dev_guide/developing_python_3.rst

Co-authored-by: Abhijeet Kasurde &lt;akasurde@redhat.com&gt;

* Apply suggestions from code review

Co-authored-by: Don Naro &lt;dnaro@redhat.com&gt;

---------

Co-authored-by: Abhijeet Kasurde &lt;akasurde@redhat.com&gt;
Co-authored-by: Don Naro &lt;dnaro@redhat.com&gt;
diff --git a/docs/docsite/rst/dev_guide/developing_collections_changelogs.rst b/docs/docsite/rst/dev_guide/developing_collections_changelogs.rst
@@ -32,7 +32,7 @@ To initialize changelog generation:
 
 #. Install ``antsibull-changelog``: :code:`pip install antsibull-changelog`.
 #. Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/collection>`.
-#. Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details.
+#. Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://ansible.readthedocs.io/projects/antsibull-changelog/changelogs/>`_ for details.
 
 To generate changelogs from the changelog fragments you created:
 
diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst
@@ -60,7 +60,7 @@ To start a new collection, run the following command in your collections directo
 
 .. note::
 
-	Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements.
+	Both the namespace and collection names use the same strict set of requirements. Both are limited to alphanumeric characters and underscores, must have a minimum length of two characters, and cannot start with an underscore.
 
 It will create the structure ``[my_namespace]/[my_collection]/[collection skeleton]``.
 
@@ -122,9 +122,9 @@ Creating collections with ansible-creator
 
    The `Ansible Development Tools <https://ansible.readthedocs.io/projects/dev-tools/>`_ package offers a convenient way to install ``ansible-creator`` along with a curated set of tools for developing automation content.
 
-After `installing <https://ansible.readthedocs.io/projects/creator/installing/#installation>`_ ``ansible-creator`` you can initialize a project in one of the following ways:
+After `installing <https://ansible.readthedocs.io/projects/creator/installing>`_ ``ansible-creator`` you can initialize a project in one of the following ways:
 
-* Use the `init <https://ansible.readthedocs.io/projects/creator/installing/#initialize-ansible-collection-init-subcommand>`_ subcommand.
+* Use the ``init`` subcommand.
 * Use ``ansible-creator`` with the `Ansible extension <https://ansible.readthedocs.io/projects/creator/collection_creation/#step-1-installing-ansible-creator-in-the-environment>`_ in Visual Studio Code.
 
 .. seealso::
diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst
@@ -291,7 +291,7 @@ execution-environment.yml
 
 If your collection has requirements, you can specify them in the ``execution-environment.yml`` file  in the ``meta`` directory.
 This ensures users do not need to add these requirements manually when building :ref:`Execution Environments<getting_started_ee_index>` containing your collection.
-See the `collection-level metadata guide <https://ansible.readthedocs.io/projects/builder/en/stable/collection_metadata/#collection-level-metadata>`_ for details.
+See the `collection-level metadata guide <https://ansible.readthedocs.io/projects/builder/en/stable/collection_metadata/>`_ for details.
 
 .. seealso::
 
diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
@@ -75,7 +75,7 @@ Since we moved to collections we have deprecated the METADATA functionality, it
 DOCUMENTATION block
 ===================
 
-After the shebang, the UTF-8 coding, the copyright line, and the license section comes the ``DOCUMENTATION`` block. Ansible's online module documentation is generated from the ``DOCUMENTATION`` blocks in each module's source code. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file. You can start by copying our `example documentation string <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_ into your module file and modifying it. If you run into syntax issues in your YAML, you can validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
+After the shebang, the UTF-8 coding, the copyright line, and the license section comes the ``DOCUMENTATION`` block. Ansible's online module documentation is generated from the ``DOCUMENTATION`` blocks in each module's source code. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file. You can start by copying our `example documentation string <https://github.com/ansible/ansible-documentation/blob/devel/examples/DOCUMENTATION.yml>`_ into your module file and modifying it. If you run into syntax issues in your YAML, you can validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
 
 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.
     * Descriptions should always start with a capital letter and end with a full stop. Consistency always helps.
diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst
@@ -644,7 +644,7 @@ the most popular ones are
 - `Powershell ISE`_
 - `Visual Studio Code`_
 
-.. _Powershell ISE: https://docs.microsoft.com/en-us/powershell/scripting/core-powershell/ise/how-to-debug-scripts-in-windows-powershell-ise
+.. _Powershell ISE: https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/ise/how-to-debug-scripts-in-windows-powershell-ise?view=powershell-7.5
 .. _Visual Studio Code: https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/06/debugging-powershell-script-in-visual-studio-code-part-1/
 
 To be able to view the arguments as passed by Ansible to the module follow
diff --git a/docs/docsite/rst/dev_guide/developing_python_3.rst b/docs/docsite/rst/dev_guide/developing_python_3.rst
@@ -372,22 +372,11 @@ is compatible with Python 2.6.
 Use percent format with byte strings
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In Python 3.x, byte strings do not have a ``format()`` method.  However, it
+In Python 3.5 and later, byte strings do not have a ``format()`` method.  However, it
 does have support for the older, percent-formatting.
 
 .. code-block:: python
 
     b_command_line = b'ansible-playbook --become-user %s -K %s' % (user, playbook_file)
 
-.. note:: Percent formatting added in Python 3.5
-
-    Percent formatting of byte strings was added back into Python 3 in 3.5.
-    This isn't a problem for us because Python 3.5 is our minimum version.
-    However, if you happen to be testing Ansible code with Python 3.4 or
-    earlier, you will find that the byte string formatting here won't work.
-    Upgrade to Python 3.5 to test.
-
-.. seealso::
-    Python documentation on `percent formatting <https://docs.python.org/3/library/stdtypes.html#string-formatting>`_
-
 .. _testing_modules_python_3:
diff --git a/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst
@@ -61,7 +61,7 @@ For menu procedures, bold the menu names, button names, and so on to help the us
 3. In the **Open** dialog box, click **Save**.
 4. On the toolbar, click the **Open File** icon.
 
-For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_:
+For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`_:
 
 .. code-block:: rst
 
diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst
@@ -174,7 +174,7 @@ For example, you can highlight Python code using following syntax:
 Internal navigation
 -------------------
 
-`Anchors (also called labels) and links <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_
+`Anchors (also called labels) and links <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref>`_
 work together to help users find related content.
 Local tables of contents also help users navigate quickly to the information they need.
 All internal links should use the ``:ref:`` syntax.
@@ -310,7 +310,7 @@ We follow these technical or mechanical guidelines on all .md pages:
 Heading notation
 ----------------
 
-`Section headings in markdown <https://daringfireball.net/projects/markdown/syntax#headers>`_
+`Section headings in markdown <https://daringfireball.net/projects/markdown/syntax#header>`_
 can use a variety of notations.
 To make our documents easy to read and to edit, we follow a standard set of heading notations.
 We use:
diff --git a/docs/docsite/rst/dev_guide/testing_units.rst b/docs/docsite/rst/dev_guide/testing_units.rst
@@ -173,7 +173,7 @@ To mock out fetching results from devices, or provide other complex data structu
 come from external libraries, you can use ``fixtures`` to read in pre-generated data.
 
 You can check how `fixtures <https://github.com/ansible/ansible/tree/devel/test/units/module_utils/facts/fixtures/cpuinfo>`_
-are used in `cpuinfo fact tests <https://github.com/ansible/ansible/blob/9f72ff80e3fe173baac83d74748ad87cb6e20e64/test/units/module_utils/facts/hardware/linux_data.py#L384>`_
+are used in `CPU_INFO_TEST_SCENARIOS <https://github.com/ansible/ansible/blob/devel/test/units/module_utils/facts/hardware/linux_data.py>`_
 
 If you are simulating APIs you may find that Python placebo is useful.  See
 :ref:`testing_units_modules` for more information.
diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst
@@ -199,14 +199,9 @@ the OS native package managers, such as `yum`, `dnf`, or `apt`, or as mentioned
 
 Refer to the documentation of the respective package for such dependencies and their installation methods.
 
-Common Platform Issues
+Common System Issues
 ++++++++++++++++++++++
 
-What customer platforms does Red Hat support?
----------------------------------------------
-
-A number of them! For a definitive list please see this `Knowledge Base article <https://access.redhat.com/articles/3168091>`_.
-
 Running in a virtualenv
 -----------------------
 
@@ -906,9 +901,8 @@ The native jinja2 functionality actually allows us to return full Python objects
 How do I submit a change to the documentation?
 ++++++++++++++++++++++++++++++++++++++++++++++
 
-Documentation for Ansible is kept in the main project Git repository, and complete instructions
-for contributing can be found in the docs README `viewable on GitHub <https://github.com/ansible/ansible/blob/devel/docs/docsite/README.md>`_. Thanks!
-
+Documentation for Ansible is kept in the `ansible/ansible-documentation <https://github.com/ansible/ansible-documentation>`_ 
+project Git repository. See :ref:`community_documentation_contributions` for details.
 
 .. _legacy_vs_builtin:
 
diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst
@@ -33,7 +33,7 @@ when a term comes up on the :ref:`Ansible Forum<ansible_forum>`.
         Name used starting with 2.11. The installable package (RPM/Python/Deb package) generated from the `ansible/ansible repository <https://github.com/ansible/ansible>`_. Contains the command-line tools and the code for basic features and functions, such as copying module code to managed nodes. The ``ansible-core`` package includes a few modules and plugins and allows you to add others by installing collections.
 
     Ansible Galaxy
-        An `online distribution server <galaxy.ansible.com>`_ for finding and sharing Ansible community content, sometimes referred to as community Galaxy. Also, the command-line utility that lets users install individual Ansible Collections, for example ``ansible-galaxy collection install community.crypto``.
+        An `online distribution server <https://galaxy.ansible.com/ui/>`_ for finding and sharing Ansible community content, sometimes referred to as community Galaxy. Also, the command-line utility that lets users install individual Ansible Collections, for example ``ansible-galaxy collection install community.crypto``.
 
     Async
         Refers to a task that is configured to run in the background rather
