diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index e638882f..f4732492 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -1,6 +1,6 @@ # Community Code of Conduct -Please see the official [Ansible Community Code of Conduct][CoC]. +Please see the official [Ansible Community Code of Conduct][coc]. -[CoC]: +[coc]: https://docs.ansible.com/ansible/latest/community/code_of_conduct.html diff --git a/docs/changelog-fragments.d/158.misc.md b/docs/changelog-fragments.d/158.misc.md index d4652c91..89e51b6b 100644 --- a/docs/changelog-fragments.d/158.misc.md +++ b/docs/changelog-fragments.d/158.misc.md @@ -1,4 +1,4 @@ -Added changelog fragment management infrastructure using [Towncrier] +Added changelog fragment management infrastructure using [Towncrier][towncrier] -- by {user}`webknjaz` -[Towncrier]: https://github.com/twisted/towncrier +[towncrier]: https://github.com/twisted/towncrier diff --git a/docs/changelog-fragments.d/161.misc.md b/docs/changelog-fragments.d/161.misc.md index 3c4e733f..090f756a 100644 --- a/docs/changelog-fragments.d/161.misc.md +++ b/docs/changelog-fragments.d/161.misc.md @@ -1,4 +1,4 @@ -Added [Sphinx] documentation generator and set up the CI +Added [Sphinx][sphinx] documentation generator and set up the CI infrastructure for it -- by {user}`webknjaz` -[Sphinx]: https://github.com/twisted/towncrier +[sphinx]: https://github.com/twisted/towncrier diff --git a/docs/changelog-fragments.d/164.doc.md b/docs/changelog-fragments.d/164.doc.md index 21ee969a..99b4e2c8 100644 --- a/docs/changelog-fragments.d/164.doc.md +++ b/docs/changelog-fragments.d/164.doc.md @@ -1,5 +1,5 @@ Dropped the brackets from the changelog titles for the release sections. -We now don't strictly follow the release notes format suggested by [Keep -a Changelog] -- by {user}`webknjaz` +We now don't strictly follow the release notes format suggested by +[Keep a Changelog][keepachangelog] -- by {user}`webknjaz` -[Keep a Changelog]: https://keepachangelog.com/en/1.1.0/ +[keepachangelog]: https://keepachangelog.com/en/1.1.0/ diff --git a/docs/changelog-fragments.d/README.md b/docs/changelog-fragments.d/README.md index 0005721a..68aa8f25 100644 --- a/docs/changelog-fragments.d/README.md +++ b/docs/changelog-fragments.d/README.md @@ -7,7 +7,8 @@ It is very important to maintain a log for news of how updating to the new version of the software will affect end-users. This is why we enforce collection of the change -fragment files in pull requests as per [Towncrier philosophy]. +fragment files in pull requests as per +[Towncrier philosophy][towncrier-philosophy]. The idea is that when somebody makes a change, they must record the bits that would affect end-users only including information @@ -32,7 +33,7 @@ for the users to understand what it means. combined with others, it will be a part of the "news digest" telling the readers **what changed** in a specific version of the library *since the previous version*. You should also use -[MyST Markdown] syntax for highlighting code (inline or block), +[MyST Markdown][myst-md] syntax for highlighting code (inline or block), linking parts of the docs or external sites. At the end, sign your change note by adding ```-- by {user}`github-username``` (replace `github-username` with @@ -73,7 +74,7 @@ See `pyproject.toml` for all available categories (`tool.towncrier.type`). ``` -[MyST Markdown]: +[myst-md]: https://myst-parser.rtfd.io/en/latest/syntax/syntax.html -[Towncrier philosophy]: +[towncrier-philosophy]: https://towncrier.rtfd.io/en/actual-freaking-docs/#philosophy diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index 3775d393..a32ac687 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -13,7 +13,7 @@ Towncrier # Contributing docs -We use [Sphinx] to generate our docs website. You can trigger +We use [Sphinx][sphinx] to generate our docs website. You can trigger the process locally by executing: ```shell-session @@ -38,21 +38,21 @@ _______________________________________________________ summary ________________ congratulations :) ``` -It is also integrated with [Read The Docs] that builds and +It is also integrated with [Read The Docs][rtd] that builds and publishes each commit to the main branch and generates live docs previews for each pull request. -The sources of the [Sphinx] documents use reStructuredText as a +The sources of the [Sphinx][sphinx] documents use reStructuredText as a de-facto standard. But in order to make contributing docs more -beginner-friendly, we have integrated [MyST parser] allowing us +beginner-friendly, we have integrated [MyST parser][myst] allowing us to also accept new documents written in an extended version of Markdown that supports using Sphinx directives and roles. {ref}`Read the docs ` to learn more on how to use it. -[MyST parser]: https://pypi.org/project/myst-parser/ -[Read The Docs]: https://readthedocs.org -[Sphinx]: https://www.sphinx-doc.org +[myst]: https://pypi.org/project/myst-parser/ +[rtd]: https://readthedocs.org +[sphinx]: https://www.sphinx-doc.org ```{include} ../changelog-fragments.d/README.md ```