[clang-tools-extra] [clang-tidy][docs] Rewrite selected rst docs to md [2/2] (PR #234571)

Sachin 🗲 via cfe-commits cfe-commits at lists.llvm.org
Fri Nov 13 05:50:16 PST 2026


https://github.com/s4chinjha updated https://github.com/llvm/llvm-project/pull/234571

>From 4e54aef9c2f69584d2569ac65d9715bd84d2a41e Mon Sep 17 00:00:00 2001
From: s4chinjha <s4chinjha at gmail.com>
Date: Wed, 21 Oct 2026 10:35:27 +0530
Subject: [PATCH 1/3] [clang-tidy][docs] Rename selected rst docs to md

---
 .../docs/clang-tidy/{Contributing.rst => Contributing.md}         | 0
 ...ternalClang-TidyExamples.rst => ExternalClang-TidyExamples.md} | 0
 .../docs/clang-tidy/{Integrations.rst => Integrations.md}         | 0
 .../{QueryBasedCustomChecks.rst => QueryBasedCustomChecks.md}     | 0
 ...ementation-in-namespace.rst => implementation-in-namespace.md} | 0
 ...ct-system-libc-headers.rst => restrict-system-libc-headers.md} | 0
 clang-tools-extra/docs/clang-tidy/{index.rst => index.md}         | 0
 7 files changed, 0 insertions(+), 0 deletions(-)
 rename clang-tools-extra/docs/clang-tidy/{Contributing.rst => Contributing.md} (100%)
 rename clang-tools-extra/docs/clang-tidy/{ExternalClang-TidyExamples.rst => ExternalClang-TidyExamples.md} (100%)
 rename clang-tools-extra/docs/clang-tidy/{Integrations.rst => Integrations.md} (100%)
 rename clang-tools-extra/docs/clang-tidy/{QueryBasedCustomChecks.rst => QueryBasedCustomChecks.md} (100%)
 rename clang-tools-extra/docs/clang-tidy/checks/llvmlibc/{implementation-in-namespace.rst => implementation-in-namespace.md} (100%)
 rename clang-tools-extra/docs/clang-tidy/checks/llvmlibc/{restrict-system-libc-headers.rst => restrict-system-libc-headers.md} (100%)
 rename clang-tools-extra/docs/clang-tidy/{index.rst => index.md} (100%)

diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.rst b/clang-tools-extra/docs/clang-tidy/Contributing.md
similarity index 100%
rename from clang-tools-extra/docs/clang-tidy/Contributing.rst
rename to clang-tools-extra/docs/clang-tidy/Contributing.md
diff --git a/clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.rst b/clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.md
similarity index 100%
rename from clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.rst
rename to clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.md
diff --git a/clang-tools-extra/docs/clang-tidy/Integrations.rst b/clang-tools-extra/docs/clang-tidy/Integrations.md
similarity index 100%
rename from clang-tools-extra/docs/clang-tidy/Integrations.rst
rename to clang-tools-extra/docs/clang-tidy/Integrations.md
diff --git a/clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.rst b/clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.md
similarity index 100%
rename from clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.rst
rename to clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.md
diff --git a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.rst b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.md
similarity index 100%
rename from clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.rst
rename to clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.md
diff --git a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.rst b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
similarity index 100%
rename from clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.rst
rename to clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.md
similarity index 100%
rename from clang-tools-extra/docs/clang-tidy/index.rst
rename to clang-tools-extra/docs/clang-tidy/index.md

>From 623c6a8732baed7e9075ea3413bd81e4d05a4e0e Mon Sep 17 00:00:00 2001
From: s4chinjha <s4chinjha at gmail.com>
Date: Wed, 21 Oct 2026 13:33:04 +0530
Subject: [PATCH 2/3] [clang-tidy][docs] Rewrite selected rst docs to md

---
 clang-tools-extra/clang-tidy/doc8.ini         |   2 +-
 clang-tools-extra/docs/clang-tidy.md          |   2 +-
 .../docs/clang-tidy/Contributing.md           | 884 ++++++++---------
 .../clang-tidy/ExternalClang-TidyExamples.md  |  34 +-
 .../docs/clang-tidy/Integrations.md           | 173 ++--
 .../docs/clang-tidy/QueryBasedCustomChecks.md | 105 +-
 .../llvmlibc/implementation-in-namespace.md   |  56 +-
 .../llvmlibc/restrict-system-libc-headers.md  |  42 +-
 clang-tools-extra/docs/clang-tidy/index.md    | 894 +++++++++---------
 clang-tools-extra/docs/conf.py                |   4 +
 10 files changed, 1044 insertions(+), 1152 deletions(-)

diff --git a/clang-tools-extra/clang-tidy/doc8.ini b/clang-tools-extra/clang-tidy/doc8.ini
index 514e75ad01df5..9b484f8e49edb 100644
--- a/clang-tools-extra/clang-tidy/doc8.ini
+++ b/clang-tools-extra/clang-tidy/doc8.ini
@@ -1,3 +1,3 @@
 [doc8]
-ignore-path = clang-tools-extra/docs/clang-tidy/Integrations.rst
+ignore-path = clang-tools-extra/docs/clang-tidy/Integrations.md
 ignore = D001
diff --git a/clang-tools-extra/docs/clang-tidy.md b/clang-tools-extra/docs/clang-tidy.md
index 6bc6e2d341ab2..2421760518116 100644
--- a/clang-tools-extra/docs/clang-tidy.md
+++ b/clang-tools-extra/docs/clang-tidy.md
@@ -7,4 +7,4 @@ orphan: true
    :http-equiv=refresh: 0;URL='clang-tidy/'
 ```
 
-clang-tidy documentation has moved here: [clang-tidy](clang-tidy/index.rst)
+clang-tidy documentation has moved here: [clang-tidy](clang-tidy/index.md)
diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.md b/clang-tools-extra/docs/clang-tidy/Contributing.md
index 71c1334428814..cee72499df420 100644
--- a/clang-tools-extra/docs/clang-tidy/Contributing.md
+++ b/clang-tools-extra/docs/clang-tidy/Contributing.md
@@ -1,286 +1,247 @@
-================
-Getting Involved
-================
+# Getting Involved
 
-:program:`clang-tidy` has several own checks and can run Clang static analyzer
+{program}`clang-tidy` has several own checks and can run Clang static analyzer
 checks, but its power is in the ability to easily write custom checks.
 
-Checks are organized in modules, which can be linked into :program:`clang-tidy`
-with minimal or no code changes in :program:`clang-tidy`.
+Checks are organized in modules, which can be linked into {program}`clang-tidy`
+with minimal or no code changes in {program}`clang-tidy`.
 
 Checks can plug into the analysis on the preprocessor level using
-`PPCallbacks`_ or on the AST level using `AST Matchers`_. When an error is
+[PPCallbacks][ppcallbacks] or on the AST level using [AST Matchers][ast matchers]. When an error is
 found, checks can report them in a way similar to how Clang diagnostics work.
 A fix-it hint can be attached to a diagnostic message.
 
-The interface provided by :program:`clang-tidy` makes it easy to write useful
+The interface provided by {program}`clang-tidy` makes it easy to write useful
 and precise checks in just a few lines of code. If you have an idea for a good
 check, the rest of this document explains how to do this.
 
 There are a few tools particularly useful when developing clang-tidy checks:
-  * ``add_new_check.py`` is a script to automate the process of adding a new
+: - `add_new_check.py` is a script to automate the process of adding a new
     check; it will create the check, update the CMake file and create a test.
-  * ``rename_check.py`` does what the script name suggests, renames an existing
+  - `rename_check.py` does what the script name suggests, renames an existing
     check.
-  * :program:`pp-trace` logs method calls on `PPCallbacks` for a source file
+  - {program}`pp-trace` logs method calls on `PPCallbacks` for a source file
     and is invaluable in understanding the preprocessor mechanism.
-  * :program:`clang-query` is invaluable for interactive prototyping of AST
+  - {program}`clang-query` is invaluable for interactive prototyping of AST
     matchers and exploration of the Clang AST;
-  * `clang-check`_ with the ``-ast-dump`` (and optionally ``-ast-dump-filter``)
+  - [clang-check][clang-check] with the `-ast-dump` (and optionally `-ast-dump-filter`)
     provides a convenient way to dump AST of a C++ program.
 
-If CMake is configured with ``CLANG_TIDY_ENABLE_STATIC_ANALYZER=NO``,
-:program:`clang-tidy` will not be built with support for the
-``clang-analyzer-*`` checks or the ``mpi-*`` checks.
+If CMake is configured with `CLANG_TIDY_ENABLE_STATIC_ANALYZER=NO`,
+{program}`clang-tidy` will not be built with support for the
+`clang-analyzer-*` checks or the `mpi-*` checks.
 
-If CMake is configured with ``CLANG_TIDY_ENABLE_QUERY_BASED_CUSTOM_CHECKS=NO``,
-:program:`clang-tidy` will not be built with support for query based checks.
+If CMake is configured with `CLANG_TIDY_ENABLE_QUERY_BASED_CUSTOM_CHECKS=NO`,
+{program}`clang-tidy` will not be built with support for query based checks.
 
-
-.. _AST Matchers: https://clang.llvm.org/docs/LibASTMatchers.html
-.. _PPCallbacks: https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html
-.. _clang-check: https://clang.llvm.org/docs/ClangCheck.html
-
-
-Choosing the Right Place for your Check
----------------------------------------
+## Choosing the Right Place for your Check
 
 If you have an idea of a check, you should decide whether it should be
 implemented as a:
 
-+ *Clang diagnostic*: if the check is generic enough, targets code patterns that
+- *Clang diagnostic*: if the check is generic enough, targets code patterns that
   most probably are bugs (rather than style or readability issues), can be
   implemented effectively and with extremely low false-positive rate, it may
   make a good Clang diagnostic.
-
-+ *Clang static analyzer check*: if the check requires some sort of control flow
+- *Clang static analyzer check*: if the check requires some sort of control flow
   analysis, it should probably be implemented as a static analyzer check.
-
-+ *clang-tidy check* is a good choice for linter-style checks, checks that are
+- *clang-tidy check* is a good choice for linter-style checks, checks that are
   related to a certain coding style, checks that address code readability, etc.
 
+## Preparing your Workspace
 
-Preparing your Workspace
-------------------------
-
-If you are new to LLVM development, you should read the `Getting Started with
-the LLVM System`_, `Using Clang Tools`_ and `How To Setup Clang Tooling For
-LLVM`_ documents to check out and build LLVM, Clang and Clang Extra Tools with
+If you are new to LLVM development, you should read the [Getting Started with
+the LLVM System][getting started with the llvm system], [Using Clang Tools][using clang tools] and [How To Setup Clang Tooling For
+LLVM][how to setup clang tooling for llvm] documents to check out and build LLVM, Clang and Clang Extra Tools with
 CMake.
 
-Once you are done, change to the ``llvm/clang-tools-extra`` directory, and
+Once you are done, change to the `llvm/clang-tools-extra` directory, and
 let's start!
 
-.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
-.. _Using Clang Tools: https://clang.llvm.org/docs/ClangTools.html
-.. _How To Setup Clang Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
-
-When you `configure the CMake build <https://llvm.org/docs/GettingStarted.html#local-llvm-configuration>`_,
-make sure that you enable the ``clang`` and ``clang-tools-extra`` projects to
-build :program:`clang-tidy`.
+When you [configure the CMake build](https://llvm.org/docs/GettingStarted.html#local-llvm-configuration),
+make sure that you enable the `clang` and `clang-tools-extra` projects to
+build {program}`clang-tidy`.
 Because your new check will have associated documentation, you will also want
-to install `Sphinx <https://www.sphinx-doc.org/en/master/>`_ and enable it in
+to install [Sphinx](https://www.sphinx-doc.org/en/master/) and enable it in
 the CMake configuration. To save build time of the core Clang libraries, you
-may want to only enable the ``X86`` target in the CMake configuration.
-
-
-The Directory Structure
------------------------
-
-:program:`clang-tidy` source code resides in the
-``llvm/clang-tools-extra`` directory and is structured as follows:
-
-::
-
-  clang-tidy/                       # Clang-tidy core.
-  |-- ClangTidy.h                   # Interfaces for users.
-  |-- ClangTidyCheck.h              # Interfaces for checks.
-  |-- ClangTidyModule.h             # Interface for clang-tidy modules.
-     ...
-  |-- google/                       # Google clang-tidy module.
-  |-+
-    |-- GoogleTidyModule.cpp
-    |-- GoogleTidyModule.h
-          ...
-  |-- llvm/                         # LLVM clang-tidy module.
-  |-+
-    |-- LLVMTidyModule.cpp
-    |-- LLVMTidyModule.h
-          ...
-  |-- objc/                         # Objective-C clang-tidy module.
-  |-+
-    |-- ObjCTidyModule.cpp
-    |-- ObjCTidyModule.h
-          ...
-  |-- tool/                         # Sources of the clang-tidy binary.
-          ...
-  test/clang-tidy/                  # Integration tests.
-      ...
-  unittests/clang-tidy/             # Unit tests.
-  |-- ClangTidyTest.h
-  |-- GoogleModuleTest.cpp
-  |-- LLVMModuleTest.cpp
-      ...
-
-
-Writing a clang-tidy Check
---------------------------
-
-So you have an idea of a useful check for :program:`clang-tidy`.
-
-First, if you're not familiar with LLVM development, read through the `Getting
-Started with the LLVM System`_ document for instructions on setting up your
-workflow and the `LLVM Coding Standards`_ document to familiarize yourself
-with the coding style used in the project. Code reviews for clang-tidy
-contributions are done through `LLVM Github`_.
+may want to only enable the `X86` target in the CMake configuration.
+
+## The Directory Structure
 
-.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
-.. _LLVM Coding Standards: https://llvm.org/docs/CodingStandards.html
-.. _LLVM Github: https://github.com/llvm/llvm-project
+{program}`clang-tidy` source code resides in the
+`llvm/clang-tools-extra` directory and is structured as follows:
+
+```
+clang-tidy/                       # Clang-tidy core.
+|-- ClangTidy.h                   # Interfaces for users.
+|-- ClangTidyCheck.h              # Interfaces for checks.
+|-- ClangTidyModule.h             # Interface for clang-tidy modules.
+   ...
+|-- google/                       # Google clang-tidy module.
+|-+
+  |-- GoogleTidyModule.cpp
+  |-- GoogleTidyModule.h
+        ...
+|-- llvm/                         # LLVM clang-tidy module.
+|-+
+  |-- LLVMTidyModule.cpp
+  |-- LLVMTidyModule.h
+        ...
+|-- objc/                         # Objective-C clang-tidy module.
+|-+
+  |-- ObjCTidyModule.cpp
+  |-- ObjCTidyModule.h
+        ...
+|-- tool/                         # Sources of the clang-tidy binary.
+        ...
+test/clang-tidy/                  # Integration tests.
+    ...
+unittests/clang-tidy/             # Unit tests.
+|-- ClangTidyTest.h
+|-- GoogleModuleTest.cpp
+|-- LLVMModuleTest.cpp
+    ...
+```
+
+## Writing a clang-tidy Check
+
+So you have an idea of a useful check for {program}`clang-tidy`.
+
+First, if you're not familiar with LLVM development, read through the [Getting
+Started with the LLVM System][getting started with the llvm system] document for instructions on setting up your
+workflow and the [LLVM Coding Standards][llvm coding standards] document to familiarize yourself
+with the coding style used in the project. Code reviews for clang-tidy
+contributions are done through [LLVM Github][llvm github].
 
 Next, you need to decide which module the check belongs to. Modules
-are located in subdirectories of `clang-tidy/
-<https://github.com/llvm/llvm-project/tree/main/clang-tools-extra/clang-tidy/>`_
+are located in subdirectories of [clang-tidy/](https://github.com/llvm/llvm-project/tree/main/clang-tools-extra/clang-tidy/)
 and contain checks targeting a certain aspect of code quality (performance,
 readability, etc.), a certain coding style or standard (Google, LLVM, CERT,
 etc.) or a widely used API (e.g. MPI). Their names are the same as the
-user-facing check group names described :ref:`above <checks-groups-table>`.
+user-facing check group names described {ref}`above <checks-groups-table>`.
 
 After choosing the module and the name for the check, run the
-``clang-tidy/add_new_check.py`` script to create the skeleton of the check and
-plug it to :program:`clang-tidy`. It's the recommended way of adding new
+`clang-tidy/add_new_check.py` script to create the skeleton of the check and
+plug it to {program}`clang-tidy`. It's the recommended way of adding new
 checks.
 
 By default, the new check will apply only to C++ code. If it should apply under
-different language options, use the ``--language`` script's parameter.
+different language options, use the `--language` script's parameter.
 
 If we want to create a `readability-awesome-function-names`, we would run:
 
-.. code-block:: console
+```console
+$ clang-tidy/add_new_check.py readability awesome-function-names
+```
 
-  $ clang-tidy/add_new_check.py readability awesome-function-names
-
-
-The ``add_new_check.py`` script will:
-  * create the class for your check inside the specified module's directory and
+The `add_new_check.py` script will:
+: - create the class for your check inside the specified module's directory and
     register it in the module and in the build system;
-  * create a lit test file in the ``test/clang-tidy/`` directory;
-  * create a documentation file and include it into the
-    ``docs/clang-tidy/checks/list.md``.
+  - create a lit test file in the `test/clang-tidy/` directory;
+  - create a documentation file and include it into the
+    `docs/clang-tidy/checks/list.md`.
 
 Let's look at the check class definition in more detail:
 
-.. code-block:: c++
+```c++
+...
 
-  ...
+#include "../ClangTidyCheck.h"
 
-  #include "../ClangTidyCheck.h"
+namespace clang::tidy::readability {
 
-  namespace clang::tidy::readability {
+...
+class AwesomeFunctionNamesCheck : public ClangTidyCheck {
+public:
+  AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+  void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+  bool isLanguageVersionSupported(const LangOptions &LangOpts) const override {
+    return LangOpts.CPlusPlus;
+  }
+};
 
-  ...
-  class AwesomeFunctionNamesCheck : public ClangTidyCheck {
-  public:
-    AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context)
-        : ClangTidyCheck(Name, Context) {}
-    void registerMatchers(ast_matchers::MatchFinder *Finder) override;
-    void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
-    bool isLanguageVersionSupported(const LangOptions &LangOpts) const override {
-      return LangOpts.CPlusPlus;
-    }
-  };
-
-  } // namespace clang::tidy::readability
+} // namespace clang::tidy::readability
 
-  ...
+...
+```
 
-Constructor of the check receives the ``Name`` and ``Context`` parameters, and
-must forward them to the ``ClangTidyCheck`` constructor.
+Constructor of the check receives the `Name` and `Context` parameters, and
+must forward them to the `ClangTidyCheck` constructor.
 
 In our case the check needs to operate on the AST level and it overrides the
-``registerMatchers`` and ``check`` methods. If we wanted to analyze code on the
-preprocessor level, we'd need instead to override the ``registerPPCallbacks``
+`registerMatchers` and `check` methods. If we wanted to analyze code on the
+preprocessor level, we'd need instead to override the `registerPPCallbacks`
 method.
 
-In the ``registerMatchers`` method, we create an AST Matcher (see `AST
-Matchers`_ for more information) that will find the pattern in the AST that we
-want to inspect. The results of the matching are passed to the ``check`` method,
+In the `registerMatchers` method, we create an AST Matcher (see [AST
+Matchers][ast matchers] for more information) that will find the pattern in the AST that we
+want to inspect. The results of the matching are passed to the `check` method,
 which can further inspect them and report diagnostics.
 
-.. code-block:: c++
+```c++
+using namespace ast_matchers;
 
-  using namespace ast_matchers;
-
-  void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) {
-    Finder->addMatcher(functionDecl().bind("x"), this);
-  }
+void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) {
+  Finder->addMatcher(functionDecl().bind("x"), this);
+}
 
-  void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) {
-    const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
-    if (!MatchedDecl->getIdentifier() || MatchedDecl->getName().startswith("awesome_"))
-      return;
-    diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome")
-        << MatchedDecl
-        << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
-  }
+void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) {
+  const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
+  if (!MatchedDecl->getIdentifier() || MatchedDecl->getName().startswith("awesome_"))
+    return;
+  diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome")
+      << MatchedDecl
+      << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
+}
+```
 
 (If you want to see an example of a useful check, look at
-`clang-tidy/misc/ExplicitConstructorCheck.h
-<https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/misc/ExplicitConstructorCheck.h>`_
-and `clang-tidy/misc/ExplicitConstructorCheck.cpp
-<https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/misc/ExplicitConstructorCheck.cpp>`_).
+[clang-tidy/misc/ExplicitConstructorCheck.h](https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/misc/ExplicitConstructorCheck.h)
+and [clang-tidy/misc/ExplicitConstructorCheck.cpp](https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/misc/ExplicitConstructorCheck.cpp)).
 
 If you need to interact with macros or preprocessor directives, you will want
-to override the method ``registerPPCallbacks``. The ``add_new_check.py``
+to override the method `registerPPCallbacks`. The `add_new_check.py`
 script does not generate an override for this method in the starting point for
 your new check.
 
-Check development tips
-----------------------
+## Check development tips
 
 Writing your first check can be a daunting task, particularly if you are
 unfamiliar with the LLVM and Clang code bases. Here are some suggestions for
 orienting yourself in the codebase and working on your check incrementally.
 
-Guide to useful documentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Guide to useful documentation
 
-Many of the support classes created for LLVM are used by Clang, such as `StringRef
-<https://llvm.org/docs/ProgrammersManual.html#the-stringref-class>`_
-and `SmallVector <https://llvm.org/docs/ProgrammersManual.html#llvm-adt-smallvector-h>`_.
-These and other commonly used classes are described in the `Important and
-useful LLVM APIs <https://llvm.org/docs/ProgrammersManual.html#important-and-useful-llvm-apis>`_
-and `Picking the Right Data Structure for the Task
-<https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task>`_
+Many of the support classes created for LLVM are used by Clang, such as [StringRef](https://llvm.org/docs/ProgrammersManual.html#the-stringref-class)
+and [SmallVector](https://llvm.org/docs/ProgrammersManual.html#llvm-adt-smallvector-h).
+These and other commonly used classes are described in the [Important and
+useful LLVM APIs](https://llvm.org/docs/ProgrammersManual.html#important-and-useful-llvm-apis)
+and [Picking the Right Data Structure for the Task](https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task)
 sections of the `LLVM Programmer's Manual
 <https://llvm.org/docs/ProgrammersManual.html>`. You don't need to memorize all the
-details of these classes; the generated `doxygen documentation <https://llvm.org/doxygen/>`_
-has everything if you need it. In the header `LLVM/ADT/STLExtras.h
-<https://llvm.org/doxygen/STLExtras_8h.html>`_ you'll find useful versions of the STL
-algorithms that operate on LLVM containers, such as `llvm::all_of
-<https://llvm.org/doxygen/STLExtras_8h.html#func-members>`_.
+details of these classes; the generated [doxygen documentation](https://llvm.org/doxygen/)
+has everything if you need it. In the header [LLVM/ADT/STLExtras.h](https://llvm.org/doxygen/STLExtras_8h.html) you'll find useful versions of the STL
+algorithms that operate on LLVM containers, such as [llvm::all_of](https://llvm.org/doxygen/STLExtras_8h.html#func-members).
 
 Clang is implemented on top of LLVM and introduces its own set of classes that
 you will interact with while writing your check. When a check issues
 diagnostics and fix-its, these are associated with locations in the source
 code. Source code locations, source files, ranges of source locations and the
-`SourceManager <https://clang.llvm.org/doxygen/classclang_1_1SourceManager.html>`_
+[SourceManager](https://clang.llvm.org/doxygen/classclang_1_1SourceManager.html)
 class provide the mechanisms for describing such locations. These and
-other topics are described in the `"Clang" CFE Internals Manual
-<https://clang.llvm.org/docs/InternalsManual.html>`_. Whereas the doxygen generated
+other topics are described in the ["Clang" CFE Internals Manual](https://clang.llvm.org/docs/InternalsManual.html). Whereas the doxygen generated
 documentation serves as a reference to the internals of Clang, this document
 serves as a guide to other developers. Topics in that manual of interest to a
 check developer are:
 
-- `The Clang "Basic" Library
-  <https://clang.llvm.org/docs/InternalsManual.html#the-clang-basic-library>`_ for
+- [The Clang "Basic" Library](https://clang.llvm.org/docs/InternalsManual.html#the-clang-basic-library) for
   information about diagnostics, fix-it hints and source locations.
-- `The Lexer and Preprocessor Library
-  <https://clang.llvm.org/docs/InternalsManual.html#the-lexer-and-preprocessor-library>`_
+- [The Lexer and Preprocessor Library](https://clang.llvm.org/docs/InternalsManual.html#the-lexer-and-preprocessor-library)
   for information about tokens, lexing (transforming characters into tokens)
   and the preprocessor.
-- `The AST Library
-  <https://clang.llvm.org/docs/InternalsManual.html#the-ast-library>`_
+- [The AST Library](https://clang.llvm.org/docs/InternalsManual.html#the-ast-library)
   for information about how C++ source statements are represented as an
   abstract syntax tree (AST).
 
@@ -296,60 +257,57 @@ nodes are matched by the AST.
 Every syntactic (and sometimes semantic) element of the C++ source code is
 represented by different classes in the AST. You select the portions of the
 AST you're interested in by composing AST matcher functions. You will want
-to study carefully the `AST Matcher Reference
-<https://clang.llvm.org/docs/LibASTMatchersReference.html>`_
+to study carefully the [AST Matcher Reference](https://clang.llvm.org/docs/LibASTMatchersReference.html)
 to understand the relationship between the different matcher functions.
 
-Using the Transformer library
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Using the Transformer library
 
 The Transformer library allows you to write a check that transforms source code
-by expressing the transformation as a ``RewriteRule``. The Transformer library
+by expressing the transformation as a `RewriteRule`. The Transformer library
 provides functions for composing edits to source code to create rewrite rules.
 Unless you need to perform low-level source location manipulation, you may want
-to consider writing your check with the Transformer library. The `Clang
-Transformer Tutorial <https://clang.llvm.org/docs/ClangTransformerTutorial.html>`_
+to consider writing your check with the Transformer library. The [Clang
+Transformer Tutorial](https://clang.llvm.org/docs/ClangTransformerTutorial.html)
 describes the Transformer library in detail.
 
 To use the Transformer library, make the following changes to the code
-generated by the ``add_new_check.py`` script:
+generated by the `add_new_check.py` script:
 
-- Include ``../utils/TransformerClangTidyCheck.h`` instead of
-  ``../ClangTidyCheck.h``
-- Change the base class of your check from ``ClangTidyCheck`` to
-  ``TransformerClangTidyCheck``
-- Delete the override of the ``registerMatchers`` and ``check`` methods in
+- Include `../utils/TransformerClangTidyCheck.h` instead of
+  `../ClangTidyCheck.h`
+- Change the base class of your check from `ClangTidyCheck` to
+  `TransformerClangTidyCheck`
+- Delete the override of the `registerMatchers` and `check` methods in
   your check class.
-- Write a function that creates the ``RewriteRule`` for your check.
+- Write a function that creates the `RewriteRule` for your check.
 - Call the function in your check's constructor to pass the rewrite rule to
-  ``TransformerClangTidyCheck``'s constructor.
+  `TransformerClangTidyCheck`'s constructor.
 
-Developing your check incrementally
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Developing your check incrementally
 
 The best way to develop your check is to start with simple test cases and
 increase complexity incrementally. The test file created by the
-``add_new_check.py`` script is a starting point for your test cases.
+`add_new_check.py` script is a starting point for your test cases.
 A rough outline of the process looks like this:
 
 - Write a test case for your check.
-- Prototype matchers on the test file using :program:`clang-query`.
-- Capture the working matchers in the ``registerMatchers`` method.
-- Issue the necessary diagnostics and fix-its in the ``check`` method.
-- Add the necessary ``CHECK-MESSAGES`` and ``CHECK-FIXES`` annotations to your
+- Prototype matchers on the test file using {program}`clang-query`.
+- Capture the working matchers in the `registerMatchers` method.
+- Issue the necessary diagnostics and fix-its in the `check` method.
+- Add the necessary `CHECK-MESSAGES` and `CHECK-FIXES` annotations to your
   test case to validate the diagnostics and fix-its.
-- Build the target ``check-clang-tools`` to confirm the test passes.
+- Build the target `check-clang-tools` to confirm the test passes.
 - Repeat the process until all aspects of your check are covered by tests.
 
-The quickest way to prototype your matcher is to use :program:`clang-query` to
+The quickest way to prototype your matcher is to use {program}`clang-query` to
 interactively build up your matcher. For complicated matchers, build up a
-matching expression incrementally and use :program:`clang-query`'s ``let``
+matching expression incrementally and use {program}`clang-query`'s `let`
 command to save named matching expressions to simplify your matcher.
 
-.. code-block:: console
-
-  clang-query> let c1 cxxRecordDecl()
-  clang-query> match c1
+```console
+clang-query> let c1 cxxRecordDecl()
+clang-query> match c1
+```
 
 Alternatively, pressing the tab key after a previous matcher's open parentheses
 would also show which matchers can be chained with the previous matcher,
@@ -361,39 +319,36 @@ intention-revealing names can help you understand a complex algorithm, breaking
 up a matcher into smaller matchers with intention-revealing names can help
 you understand a complicated matcher.
 
-Once you have a working :program:`clang-query` matcher, the C++ API matchers
+Once you have a working {program}`clang-query` matcher, the C++ API matchers
 will be the same or similar to your interactively constructed matcher (there
 can be cases where they differ slightly). You can use local variables to
 preserve your intention-revealing names that you applied to nested matchers.
 
-Creating private matchers
-^^^^^^^^^^^^^^^^^^^^^^^^^
+### Creating private matchers
 
 Sometimes you want to match a specific aspect of the AST that isn't provided
 by the existing AST matchers. You can create your own private matcher using
 the same infrastructure as the public matchers. A private matcher can
-simplify the processing in your ``check`` method by eliminating complex
+simplify the processing in your `check` method by eliminating complex
 hand-crafted AST traversal of the matched nodes. Using the private matcher
 allows you to select the desired portions of the AST directly in the matcher
-and refer to it by a bound name in the ``check`` method.
+and refer to it by a bound name in the `check` method.
 
-Unit testing helper code
-^^^^^^^^^^^^^^^^^^^^^^^^
+### Unit testing helper code
 
 Private custom matchers are a good example of auxiliary support code for your
 check that can be tested with a unit test. It will be easier to test your
 matchers or other support classes by writing a unit test than by writing a
-``FileCheck`` integration test. The ``ASTMatchersTests`` target contains unit
+`FileCheck` integration test. The `ASTMatchersTests` target contains unit
 tests for the public AST matcher classes and is a good source of testing
 idioms for matchers.
 
-You can build the Clang-Tidy unit tests by building the ``ClangTidyTests``
+You can build the Clang-Tidy unit tests by building the `ClangTidyTests`
 target. Test targets in LLVM and Clang are excluded from the "build all" style
 action of IDE-based CMake generators, so you need to explicitly build the
 target for the unit tests to be built.
 
-Making your check robust
-^^^^^^^^^^^^^^^^^^^^^^^^
+### Making your check robust
 
 Once you've covered your check with the basic "happy path" scenarios, you'll
 want to torture your check with as many edge cases as you can cover in order to
@@ -409,16 +364,16 @@ Some suggestions to ensure your check is robust:
 
 - Create header files that contain code matched by your check.
 - Validate that fix-its are properly applied to test header files with
-  :program:`clang-tidy`. You will need to perform this test manually until
+  {program}`clang-tidy`. You will need to perform this test manually until
   automated support for checking messages and fix-its is added to the
-  ``check_clang_tidy.py`` script.
+  `check_clang_tidy.py` script.
 - Define macros that contain code matched by your check.
 - Define template classes that contain code matched by your check.
 - Define template specializations that contain code matched by your check.
 - Test your check under both Windows and Linux environments. For example, when
   a fix-it inserts new lines, use the source file's existing newline style
-  instead of hard-coding ``\n``. You can use
-  ``SourceManager::getBufferData(FileID).detectEOL()`` to get the newline style
+  instead of hard-coding `\n`. You can use
+  `SourceManager::getBufferData(FileID).detectEOL()` to get the newline style
   for a file.
 - Watch out for high false-positive rates. Ideally, a check would have no
   false positives, but given that matching against an AST is not control-
@@ -432,17 +387,16 @@ Some suggestions to ensure your check is robust:
   check.
 - Consider supporting a code pattern to allow the programmer to silence the
   diagnostic whenever such a code pattern can clearly express the programmer's
-  intent. For example, allowing an explicit cast to ``void`` to silence an
+  intent. For example, allowing an explicit cast to `void` to silence an
   unused variable diagnostic.
 - Consider adding check configuration options to allow the user to opt into
   more aggressive checking behavior without burdening users for the common
   high-confidence cases.
 
-Documenting your check
-^^^^^^^^^^^^^^^^^^^^^^
+### Documenting your check
 
-The ``add_new_check.py`` script creates entries in the
-:doc:`release notes </ReleaseNotes>`, the list of
+The `add_new_check.py` script creates entries in the
+{doc}`release notes </ReleaseNotes>`, the list of
 
 checks and a new file for the check documentation itself. It is recommended
 that you have a concise summary of what your check does in a single sentence
@@ -457,7 +411,7 @@ style guide sections in your check documentation.
 
 Checks that directly reference MISRA or AUTOSAR guidelines are not accepted
 due to legal/license reasons; see
-`this Discourse thread <https://discourse.llvm.org/t/will-clang-frontend-plan-accept-misra-check-tools/84754>`_.
+[this Discourse thread](https://discourse.llvm.org/t/will-clang-frontend-plan-accept-misra-check-tools/84754).
 Generic checks that happen to overlap with those guidelines are fine as long as
 they do not claim to implement or link to MISRA/AUTOSAR rules.
 
@@ -467,210 +421,204 @@ is run. If there are exceptions or limitations to your check, document them
 thoroughly. This will help users understand the scope of the diagnostics and
 fix-its provided by the check.
 
-Building the target ``docs-clang-tools-html`` will run the Sphinx documentation
+Building the target `docs-clang-tools-html` will run the Sphinx documentation
 generator and create HTML documentation files in the
-``tools/clang/tools/extra/docs/html`` directory in your build tree.
+`tools/clang/tools/extra/docs/html` directory in your build tree.
 Make sure that your check is correctly shown in the release notes and the list
 of checks, and that its documentation is formatted and structured correctly.
 
-Registering your Check
-----------------------
+## Registering your Check
 
-(The ``add_new_check.py`` script takes care of registering the check in an
+(The `add_new_check.py` script takes care of registering the check in an
 existing module. If you want to create a new module or know the details,
 read on.)
 
 The check should be registered in the corresponding module with a distinct
 name:
 
-.. code-block:: c++
-
-  class MyModule : public ClangTidyModule {
-   public:
-    void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
-      CheckFactories.registerCheck<ExplicitConstructorCheck>(
-          "my-explicit-constructor");
-    }
-  };
+```c++
+class MyModule : public ClangTidyModule {
+ public:
+  void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+    CheckFactories.registerCheck<ExplicitConstructorCheck>(
+        "my-explicit-constructor");
+  }
+};
+```
 
-Now we need to register the module in the ``ClangTidyModuleRegistry`` using a
+Now we need to register the module in the `ClangTidyModuleRegistry` using a
 statically initialized variable:
 
-.. code-block:: c++
-
-  static ClangTidyModuleRegistry::Add<MyModule> X("my-module",
-                                                  "Adds my lint checks.");
-
+```c++
+static ClangTidyModuleRegistry::Add<MyModule> X("my-module",
+                                                "Adds my lint checks.");
+```
 
 When using LLVM build system, we need to use the following hack to ensure the
-module is linked into the :program:`clang-tidy` binary:
-
-Add this near the ``ClangTidyModuleRegistry::Add<MyModule>`` variable:
-
-.. code-block:: c++
+module is linked into the {program}`clang-tidy` binary:
 
-  // This anchor is used to force the linker to link in the generated object file
-  // and thus register the MyModule.
-  volatile int MyModuleAnchorSource = 0;
+Add this near the `ClangTidyModuleRegistry::Add<MyModule>` variable:
 
-And this to the main translation unit of the :program:`clang-tidy` binary (or
-the binary you link the ``clang-tidy`` library in)
-``clang-tidy/ClangTidyForceLinker.h``:
+```c++
+// This anchor is used to force the linker to link in the generated object file
+// and thus register the MyModule.
+volatile int MyModuleAnchorSource = 0;
+```
 
-.. code-block:: c++
+And this to the main translation unit of the {program}`clang-tidy` binary (or
+the binary you link the `clang-tidy` library in)
+`clang-tidy/ClangTidyForceLinker.h`:
 
-  // This anchor is used to force the linker to link the MyModule.
-  extern volatile int MyModuleAnchorSource;
-  static int MyModuleAnchorDestination = MyModuleAnchorSource;
+```c++
+// This anchor is used to force the linker to link the MyModule.
+extern volatile int MyModuleAnchorSource;
+static int MyModuleAnchorDestination = MyModuleAnchorSource;
+```
 
-
-Configuring Checks
-------------------
+## Configuring Checks
 
 If a check needs configuration options, it can access check-specific options
-using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check
+using the `Options.get<Type>("SomeOption", DefaultValue)` call in the check
 constructor. In this case, the check should also override the
-``ClangTidyCheck::storeOptions`` method to make the options provided by the
-check discoverable. This method lets :program:`clang-tidy` know which options
+`ClangTidyCheck::storeOptions` method to make the options provided by the
+check discoverable. This method lets {program}`clang-tidy` know which options
 the check implements and what the current values are (e.g. for the
-``-dump-config`` command-line option).
-
-.. code-block:: c++
-
-  class MyCheck : public ClangTidyCheck {
-    const unsigned SomeOption1;
-    const std::string SomeOption2;
-
-  public:
-    MyCheck(StringRef Name, ClangTidyContext *Context)
-      : ClangTidyCheck(Name, Context),
-        SomeOption1(Options.get("SomeOption1", -1U)),
-        SomeOption2(Options.get("SomeOption2", "some default")) {}
-
-    void storeOptions(ClangTidyOptions::OptionMap &Opts) override {
-      Options.store(Opts, "SomeOption1", SomeOption1);
-      Options.store(Opts, "SomeOption2", SomeOption2);
-    }
-    ...
+`-dump-config` command-line option).
+
+```c++
+class MyCheck : public ClangTidyCheck {
+  const unsigned SomeOption1;
+  const std::string SomeOption2;
+
+public:
+  MyCheck(StringRef Name, ClangTidyContext *Context)
+    : ClangTidyCheck(Name, Context),
+      SomeOption1(Options.get("SomeOption1", -1U)),
+      SomeOption2(Options.get("SomeOption2", "some default")) {}
+
+  void storeOptions(ClangTidyOptions::OptionMap &Opts) override {
+    Options.store(Opts, "SomeOption1", SomeOption1);
+    Options.store(Opts, "SomeOption2", SomeOption2);
+  }
+  ...
+```
 
 Assuming the check is registered with the name "my-check", the option can then
-be set in a ``.clang-tidy`` file in the following way:
+be set in a `.clang-tidy` file in the following way:
 
-.. code-block:: yaml
-
-  CheckOptions:
-    my-check.SomeOption1: 123
-    my-check.SomeOption2: 'some other value'
+```yaml
+CheckOptions:
+  my-check.SomeOption1: 123
+  my-check.SomeOption2: 'some other value'
+```
 
 If you need to specify check options on a command line, you can use the inline
 YAML format:
 
-.. code-block:: console
-
-  $ clang-tidy -config="{CheckOptions: {a: b, x: y}}" ...
+```console
+$ clang-tidy -config="{CheckOptions: {a: b, x: y}}" ...
+```
 
+## Testing Checks
 
-Testing Checks
---------------
-
-To run tests for :program:`clang-tidy`, build the ``check-clang-tools``
+To run tests for {program}`clang-tidy`, build the `check-clang-tools`
 target. For instance, if you configured your CMake build with the ninja project
 generator, use the command:
 
-.. code-block:: console
-
-  $ ninja check-clang-tools
+```console
+$ ninja check-clang-tools
+```
 
-:program:`clang-tidy` checks can be tested using either unit tests or
-`lit`_ tests. Unit tests may be more convenient to test complex replacements
-with strict checks. `Lit`_ tests allow using partial text matching and regular
+{program}`clang-tidy` checks can be tested using either unit tests or
+[lit][lit] tests. Unit tests may be more convenient to test complex replacements
+with strict checks. [Lit][lit] tests allow using partial text matching and regular
 expressions which makes them more suitable for writing compact tests for
 diagnostic messages.
 
-The ``check_clang_tidy.py`` script provides an easy way to test both
-diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test
-file, runs :program:`clang-tidy` and verifies messages and fixes with two
-separate `FileCheck`_ invocations: once with FileCheck's directive
-prefix set to ``CHECK-MESSAGES``, validating the diagnostic messages,
-and once with the directive prefix set to ``CHECK-FIXES``, running
+The `check_clang_tidy.py` script provides an easy way to test both
+diagnostic messages and fix-its. It filters out `CHECK` lines from the test
+file, runs {program}`clang-tidy` and verifies messages and fixes with two
+separate [FileCheck][filecheck] invocations: once with FileCheck's directive
+prefix set to `CHECK-MESSAGES`, validating the diagnostic messages,
+and once with the directive prefix set to `CHECK-FIXES`, running
 against the fixed code (i.e., the code after generated fix-its are
-applied). In particular, ``CHECK-FIXES:`` can be used to check
+applied). In particular, `CHECK-FIXES:` can be used to check
 that code was not modified by fix-its, by checking that it is present
-unchanged in the fixed code. The full set of `FileCheck`_ directives
-is available (e.g., ``CHECK-MESSAGES-SAME:``, ``CHECK-MESSAGES-NOT:``), though
-typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``)
-are sufficient for clang-tidy tests. Note that the `FileCheck`_
-documentation mostly assumes the default prefix (``CHECK``), and hence
-describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc.
-Replace ``CHECK`` with either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for
+unchanged in the fixed code. The full set of [FileCheck][filecheck] directives
+is available (e.g., `CHECK-MESSAGES-SAME:`, `CHECK-MESSAGES-NOT:`), though
+typically the basic `CHECK` forms (`CHECK-MESSAGES` and `CHECK-FIXES`)
+are sufficient for clang-tidy tests. Note that the [FileCheck][filecheck]
+documentation mostly assumes the default prefix (`CHECK`), and hence
+describes the directive as `CHECK:`, `CHECK-SAME:`, `CHECK-NOT:`, etc.
+Replace `CHECK` with either `CHECK-FIXES` or `CHECK-MESSAGES` for
 clang-tidy tests.
 
-An additional check enabled by ``check_clang_tidy.py`` ensures that
+An additional check enabled by `check_clang_tidy.py` ensures that
 if `CHECK-MESSAGES:` is used in a file then every warning or error
-must have an associated CHECK in that file. Or, you can use ``CHECK-NOTES:``
+must have an associated CHECK in that file. Or, you can use `CHECK-NOTES:`
 instead, if you want to **also** ensure that all the notes are checked.
 
-To use the ``check_clang_tidy.py`` script, put a .cpp file with the
-appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use
-``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against
+To use the `check_clang_tidy.py` script, put a .cpp file with the
+appropriate `RUN` line in the `test/clang-tidy` directory. Use
+`CHECK-MESSAGES:` and `CHECK-FIXES:` lines to write checks against
 diagnostic messages and fixed code.
 
 It's advised to make the checks as specific as possible to avoid checks
-matching incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]``
+matching incorrect parts of the input. Use `[[@LINE+X]]`/`[[@LINE-X]]`
 substitutions and distinct function and variable names in the test code.
 
-Here's an example of a test using the ``check_clang_tidy.py`` script (the full
-source code is at `test/clang-tidy/checkers/google/readability-casting.cpp`_):
+Here's an example of a test using the `check_clang_tidy.py` script (the full
+source code is at [test/clang-tidy/checkers/google/readability-casting.cpp][test/clang-tidy/checkers/google/readability-casting.cpp]):
 
-.. code-block:: c++
+```c++
+// RUN: %check_clang_tidy %s google-readability-casting %t
 
-  // RUN: %check_clang_tidy %s google-readability-casting %t
-
-  void f(int a) {
-    int b = (int)a;
-    // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting]
-    // CHECK-FIXES: int b = a;
-  }
+void f(int a) {
+  int b = (int)a;
+  // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting]
+  // CHECK-FIXES: int b = a;
+}
+```
 
 To check more than one scenario in the same test file, use
-``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or
-``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``.
-With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*``
-directives with ``CHECK-MESSAGES-SUFFIX-NAME`` and ``CHECK-FIXES-SUFFIX-NAME``.
+`-check-suffix=SUFFIX-NAME` on `check_clang_tidy.py` command line or
+`-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...`.
+With `-check-suffix[es]=SUFFIX-NAME` you need to replace your `CHECK-*`
+directives with `CHECK-MESSAGES-SUFFIX-NAME` and `CHECK-FIXES-SUFFIX-NAME`.
 
 Here's an example:
 
-.. code-block:: c++
-
-   // RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A
-   // RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B
-   // RUN: %check_clang_tidy %s misc-unused-using-decls %t
-   ...
-   // CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}}
-   // CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}}
-   // CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}}
-   // CHECK-FIXES-USING-A-NOT: using a::A;$
-   // CHECK-FIXES-USING-B-NOT: using a::B;$
-   // CHECK-FIXES-NOT: using a::C;$
-
-The ``-std`` flag controls which C or C++ standard(s) the test is compiled
+```c++
+// RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A
+// RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B
+// RUN: %check_clang_tidy %s misc-unused-using-decls %t
+...
+// CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}}
+// CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}}
+// CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}}
+// CHECK-FIXES-USING-A-NOT: using a::A;$
+// CHECK-FIXES-USING-B-NOT: using a::B;$
+// CHECK-FIXES-NOT: using a::C;$
+```
+
+The `-std` flag controls which C or C++ standard(s) the test is compiled
 under. It accepts a comma-separated list of standards and supports
-``-or-later`` and ``-or-earlier`` suffixes:
+`-or-later` and `-or-earlier` suffixes:
 
-- ``-std=c++17``: runs the test **only** with C++17.
-- ``-std=c++17-or-later``: runs the test once for each standard from C++17
+- `-std=c++17`: runs the test **only** with C++17.
+- `-std=c++17-or-later`: runs the test once for each standard from C++17
   onwards (currently C++17, C++20, C++23, and C++26), in separate invocations.
   Use this when a check should work correctly on all modern standards.
-- ``-std=c++17-or-earlier``: runs the test once for each standard up to and
+- `-std=c++17-or-earlier`: runs the test once for each standard up to and
   including C++17 (currently C++98, C++11, C++14, and C++17), in separate
   invocations. Use this when a check should work correctly on all older
   standards.
-- ``-std=c++14,c++17``: runs the test once with C++14 and once with C++17.
+- `-std=c++14,c++17`: runs the test once with C++14 and once with C++17.
 
-When no ``-std`` is given, ``check_clang_tidy.py`` defaults to
-``c++11-or-later`` for C++ files and ``c99-or-later`` for C files. The check
-skeleton generated by ``add_new_check.py`` uses the ``-or-later`` form by
-default. Prefer ``-std=<minimum>-or-later`` unless the test expects
+When no `-std` is given, `check_clang_tidy.py` defaults to
+`c++11-or-later` for C++ files and `c99-or-later` for C files. The check
+skeleton generated by `add_new_check.py` uses the `-or-later` form by
+default. Prefer `-std=<minimum>-or-later` unless the test expects
 behavior that only applies to a specific standard version.
 
 There are many dark corners in the C++ language, and it may be difficult to
@@ -682,8 +630,8 @@ hints. The most frequent pitfalls are macros and templates:
 2. Multiple macro expansions/template instantiations may result in the
    same code being inspected by the check multiple times (possibly, with
    different meanings, see 1), and the same warning (or a slightly different
-   one) may be issued by the check multiple times; :program:`clang-tidy` will
-   deduplicate _identical_ warnings, but if the warnings are slightly
+   one) may be issued by the check multiple times; {program}`clang-tidy` will
+   deduplicate \_identical\_ warnings, but if the warnings are slightly
    different, all of them will be shown to the user (and used for applying
    fixes, if any).
 3. Making replacements to a macro body/template definition may be fine for
@@ -692,58 +640,49 @@ hints. The most frequent pitfalls are macros and templates:
 
 If you need multiple files to exercise all the aspects of your check, it is
 recommended you place them in a subdirectory named for the check under the
-``Inputs`` directory for the module containing your check. This keeps the
+`Inputs` directory for the module containing your check. This keeps the
 test directory from getting cluttered.
 
 If you need to validate how your check interacts with system header files, a
 set of simulated system header files is located in the
-``checkers/Inputs/Headers`` directory. The path to this directory is
-available in a lit test with the variable ``%clang_tidy_headers``.
+`checkers/Inputs/Headers` directory. The path to this directory is
+available in a lit test with the variable `%clang_tidy_headers`.
 
-.. _lit: https://llvm.org/docs/CommandGuide/lit.html
-.. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html
-.. _test/clang-tidy/checkers/google/readability-casting.cpp: https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/checkers/google/readability-casting.cpp
-
-
-Submitting a Pull Request
--------------------------
+## Submitting a Pull Request
 
 Before submitting a pull request, contributors are encouraged to run
-:program:`clang-tidy` and :program:`clang-format` on their changes to ensure
-code quality and catch potential issues. While :program:`clang-tidy` is not
+{program}`clang-tidy` and {program}`clang-format` on their changes to ensure
+code quality and catch potential issues. While {program}`clang-tidy` is not
 currently enforced in CI, following this practice helps maintain code
 consistency and prevent common errors.
 
 Here's a useful command to check your staged changes:
 
-.. code-block:: console
-
-  $ git diff --staged -U0 | ./clang-tools-extra/clang-tidy/tool/clang-tidy-diff.py \
-      -j $(nproc) -path build/ -p1 -only-check-in-db
-  $ git clang-format
+```console
+$ git diff --staged -U0 | ./clang-tools-extra/clang-tidy/tool/clang-tidy-diff.py \
+    -j $(nproc) -path build/ -p1 -only-check-in-db
+$ git clang-format
+```
 
 Note that some warnings may be false positives or require careful consideration
 before fixing. Use your judgment and feel free to discuss in the pull request
 if you're unsure about a particular warning.
 
-
-Out-of-tree check plugins
--------------------------
-
+## Out-of-tree check plugins
 
 Developing an out-of-tree check as a plugin largely follows the steps
 outlined above, including creating a new module and doing the hacks to
 register the module. The plugin is a shared library whose code lives outside
 the clang-tidy build system. Build and link this shared library against
 LLVM as done for other kinds of Clang plugins. If using CMake, use the keyword
-``MODULE`` while invoking ``add_library`` or ``llvm_add_library``.
+`MODULE` while invoking `add_library` or `llvm_add_library`.
 
 The plugin can be loaded by passing `-load` to `clang-tidy` in addition to the
 names of the checks to enable.
 
-.. code-block:: console
-
-  $ clang-tidy --checks=-*,my-explicit-constructor -list-checks -load myplugin.so
+```console
+$ clang-tidy --checks=-*,my-explicit-constructor -list-checks -load myplugin.so
+```
 
 There are no expectations regarding ABI and API stability, so the plugin must
 be compiled against the version of clang-tidy that will be loading the plugin.
@@ -751,116 +690,115 @@ be compiled against the version of clang-tidy that will be loading the plugin.
 The plugins can use threads, TLS, or any other facilities available to in-tree
 code which is accessible from the external headers.
 
-Note that testing out-of-tree checks might involve getting ``llvm-lit`` from an
-LLVM installation compiled from source. See `Getting Started with the LLVM
-System`_ for ways to do so.
+Note that testing out-of-tree checks might involve getting `llvm-lit` from an
+LLVM installation compiled from source. See [Getting Started with the LLVM
+System][getting started with the llvm system] for ways to do so.
 
-Alternatively, get `lit`_ following the `test-suite guide`_ and get the
-`FileCheck`_ binary, and write a version of `check_clang_tidy.py`_ to suit your
+Alternatively, get [lit][lit] following the [test-suite guide][test-suite guide] and get the
+[FileCheck][filecheck] binary, and write a version of [check_clang_tidy.py][check_clang_tidy.py] to suit your
 needs.
 
-.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
-.. _test-suite guide: https://llvm.org/docs/TestSuiteGuide.html
-.. _lit: https://llvm.org/docs/CommandGuide/lit.html
-.. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html
-.. _check_clang_tidy.py: https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/check_clang_tidy.py
-
-Running clang-tidy on LLVM
---------------------------
+## Running clang-tidy on LLVM
 
 To test a check, it's best to try it out on a larger code base. LLVM and Clang
 are the natural targets as you already have the source code around. The most
-convenient way to run :program:`clang-tidy` is with a compile command database;
+convenient way to run {program}`clang-tidy` is with a compile command database;
 CMake can automatically generate one; for a description of how to enable it,
-see `How To Setup Clang Tooling For LLVM`_. Once ``compile_commands.json`` is
-in place and a working version of :program:`clang-tidy` is in ``PATH`` the
-entire code base can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``.
-The script executes :program:`clang-tidy` with the default set of checks on
+see [How To Setup Clang Tooling For LLVM][how to setup clang tooling for llvm]. Once `compile_commands.json` is
+in place and a working version of {program}`clang-tidy` is in `PATH` the
+entire code base can be analyzed with `clang-tidy/tool/run-clang-tidy.py`.
+The script executes {program}`clang-tidy` with the default set of checks on
 every translation unit in the compile command database and displays the
 resulting warnings and errors. The script provides multiple configuration
 flags.
 
-.. _How To Setup Clang Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
-
-
-* The default set of checks can be overridden using the ``-checks`` argument,
-  taking the identical format as :program:`clang-tidy` does. For example,
-  ``-checks=-*,modernize-use-override`` will run the ``modernize-use-override``
+- The default set of checks can be overridden using the `-checks` argument,
+  taking the identical format as {program}`clang-tidy` does. For example,
+  `-checks=-*,modernize-use-override` will run the `modernize-use-override`
   check only.
-
-* To restrict the files examined, you can provide one or more regex arguments
+- To restrict the files examined, you can provide one or more regex arguments
   that the file names are matched against.
-  ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze `clang-tidy`
+  `run-clang-tidy.py clang-tidy/.*Check\.cpp` will only analyze `clang-tidy`
   checks. It may also be necessary to restrict the header files that warnings
-  are displayed from by using the ``-header-filter`` and
-  ``-exclude-header-filter`` flags. They have the same behavior as the
-  corresponding :program:`clang-tidy` flags.
-
-* To apply suggested fixes, ``-fix`` can be passed as an argument. This gathers
-  all changes in a temporary directory and applies them. Passing ``-format``
+  are displayed from by using the `-header-filter` and
+  `-exclude-header-filter` flags. They have the same behavior as the
+  corresponding {program}`clang-tidy` flags.
+- To apply suggested fixes, `-fix` can be passed as an argument. This gathers
+  all changes in a temporary directory and applies them. Passing `-format`
   will run clang-format over changed lines.
 
+## On checks profiling
 
-On checks profiling
--------------------
-
-:program:`clang-tidy` can collect per-check profiling info, and output it
+{program}`clang-tidy` can collect per-check profiling info, and output it
 for each processed source file (translation unit).
 
-To enable profiling info collection, use the ``-enable-check-profile``
-argument. The timings will be output to ``stderr`` as a table.
+To enable profiling info collection, use the `-enable-check-profile`
+argument. The timings will be output to `stderr` as a table.
 Example output:
 
-.. code-block:: console
+```console
+$ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp
+===-------------------------------------------------------------------------===
+                          clang-tidy checks profiling
+===-------------------------------------------------------------------------===
+  Total Execution Time: 1.0282 seconds (1.0258 wall clock)
 
-  $ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp
-  ===-------------------------------------------------------------------------===
-                            clang-tidy checks profiling
-  ===-------------------------------------------------------------------------===
-    Total Execution Time: 1.0282 seconds (1.0258 wall clock)
-
-     ---User Time---   --System Time--   --User+System--   ---Wall Time---  --- Name ---
-     0.9136 (100.0%)   0.1146 (100.0%)   1.0282 (100.0%)   1.0258 (100.0%)  readability-function-size
-     0.9136 (100.0%)   0.1146 (100.0%)   1.0282 (100.0%)   1.0258 (100.0%)  Total
+   ---User Time---   --System Time--   --User+System--   ---Wall Time---  --- Name ---
+   0.9136 (100.0%)   0.1146 (100.0%)   1.0282 (100.0%)   1.0258 (100.0%)  readability-function-size
+   0.9136 (100.0%)   0.1146 (100.0%)   1.0282 (100.0%)   1.0258 (100.0%)  Total
+```
 
 It can also store that data as JSON files for further processing.
 Example output:
 
-.. code-block:: console
-
-  $ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp
-  $ # Note that there won't be timings table printed to the console.
-  $ ls /tmp/out/
-  20180516161318717446360-source.cpp.json
-  $ cat 20180516161318717446360-source.cpp.json
-  {
-  "file": "/path/to/source.cpp",
-  "timestamp": "2018-05-16 16:13:18.717446360",
-  "profile": {
-    "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00,
-    "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01,
-    "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01
-  }
-  }
+```console
+$ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp
+$ # Note that there won't be timings table printed to the console.
+$ ls /tmp/out/
+20180516161318717446360-source.cpp.json
+$ cat 20180516161318717446360-source.cpp.json
+{
+"file": "/path/to/source.cpp",
+"timestamp": "2018-05-16 16:13:18.717446360",
+"profile": {
+  "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00,
+  "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01,
+  "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01
+}
+}
+```
 
 There is only one argument that controls profile storage:
 
-* ``-store-check-profile=<prefix>``
+- `-store-check-profile=<prefix>`
 
   By default, reports are printed in tabulated format to stderr. When this
   option is passed, these per-TU profiles are instead stored as JSON.
   If the prefix is not an absolute path, it is considered to be relative to the
-  directory from where you have run :program:`clang-tidy`. All ``.`` and ``..``
+  directory from where you have run {program}`clang-tidy`. All `.` and `..`
   patterns in the path are collapsed, and symlinks are resolved.
 
   Example:
-  Let's suppose you have a source file named ``example.cpp``, located in the
-  ``/source`` directory. Only the input filename is used, not the full path
+  Let's suppose you have a source file named `example.cpp`, located in the
+  `/source` directory. Only the input filename is used, not the full path
   to the source file. Additionally, it is prefixed with the current timestamp.
 
-  * If you specify ``-store-check-profile=/tmp``, then the profile will be
-    saved to ``/tmp/<ISO8601-like timestamp>-example.cpp.json``
-
-  * If you run :program:`clang-tidy` from within ``/foo`` directory, and
-    specify ``-store-check-profile=.``, then the profile will still be
-    saved to ``/foo/<ISO8601-like timestamp>-example.cpp.json``
+  - If you specify `-store-check-profile=/tmp`, then the profile will be
+    saved to `/tmp/<ISO8601-like timestamp>-example.cpp.json`
+  - If you run {program}`clang-tidy` from within `/foo` directory, and
+    specify `-store-check-profile=.`, then the profile will still be
+    saved to `/foo/<ISO8601-like timestamp>-example.cpp.json`
+
+[ast matchers]: https://clang.llvm.org/docs/LibASTMatchers.html
+[check_clang_tidy.py]: https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/check_clang_tidy.py
+[clang-check]: https://clang.llvm.org/docs/ClangCheck.html
+[filecheck]: https://llvm.org/docs/CommandGuide/FileCheck.html
+[getting started with the llvm system]: https://llvm.org/docs/GettingStarted.html
+[how to setup clang tooling for llvm]: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
+[lit]: https://llvm.org/docs/CommandGuide/lit.html
+[llvm coding standards]: https://llvm.org/docs/CodingStandards.html
+[llvm github]: https://github.com/llvm/llvm-project
+[ppcallbacks]: https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html
+[test-suite guide]: https://llvm.org/docs/TestSuiteGuide.html
+[test/clang-tidy/checkers/google/readability-casting.cpp]: https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/checkers/google/readability-casting.cpp
+[using clang tools]: https://clang.llvm.org/docs/ClangTools.html
diff --git a/clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.md b/clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.md
index 9b9b48478447a..018a929d6871d 100644
--- a/clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.md
+++ b/clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.md
@@ -1,31 +1,27 @@
-============================
-External Clang-Tidy Examples
-============================
+# External Clang-Tidy Examples
 
-Introduction
-============
+## Introduction
 
-This page provides examples of what people have done with :program:`clang-tidy`
+This page provides examples of what people have done with {program}`clang-tidy`
 that might serve as useful guides (or starting points) to develop your own
 checks. They may be helpful for necessary things such as how to write the
-`CMakeLists.txt` for an out-of-tree plugin of :program:`clang-tidy` checks.
+`CMakeLists.txt` for an out-of-tree plugin of {program}`clang-tidy` checks.
 
-If you know of (or wrote!) a tool or project using :program:`clang-tidy`,
-please share it on `the Discourse forums (Clang Frontend category)
-<https://discourse.llvm.org/c/clang/6>`_ for wider visibility and open a
-pull-request on `LLVM Github`_ to have it added here. Since the primary
+If you know of (or wrote!) a tool or project using {program}`clang-tidy`,
+please share it on [the Discourse forums (Clang Frontend category)](https://discourse.llvm.org/c/clang/6) for wider visibility and open a
+pull-request on [LLVM Github][llvm github] to have it added here. Since the primary
 purpose of this page is to provide examples that can help developers, the
 listed projects should have code available.
 
-As :program:`clang-tidy` is using, for example, the AST Matchers and
-diagnostics of Clang, `External Clang Examples`_ may also be useful to look at
+As {program}`clang-tidy` is using, for example, the AST Matchers and
+diagnostics of Clang, [External Clang Examples][external clang examples] may also be useful to look at
 for such examples.
 
-.. _LLVM Github: https://github.com/llvm/llvm-project
-.. _External Clang Examples: https://clang.llvm.org/docs/ExternalClangExamples.html
+## List of projects and tools
 
-List of projects and tools
-==========================
+[https://github.com/coveooss/clang-tidy-plugin-examples](https://github.com/coveooss/clang-tidy-plugin-examples)
 
-`<https://github.com/coveooss/clang-tidy-plugin-examples>`_
-    "This folder contains :program:`clang-tidy` plugins."
+: "This folder contains {program}`clang-tidy` plugins."
+
+[external clang examples]: https://clang.llvm.org/docs/ExternalClangExamples.html
+[llvm github]: https://github.com/llvm/llvm-project
diff --git a/clang-tools-extra/docs/clang-tidy/Integrations.md b/clang-tools-extra/docs/clang-tidy/Integrations.md
index e8cb03524ab34..c836dfb9521c8 100644
--- a/clang-tools-extra/docs/clang-tidy/Integrations.md
+++ b/clang-tools-extra/docs/clang-tidy/Integrations.md
@@ -1,123 +1,100 @@
-==================================
-Clang-tidy IDE/Editor Integrations
-==================================
+# Clang-tidy IDE/Editor Integrations
 
-.. _clangd: http://clangd.llvm.org/
-.. _is available: https://clangd.llvm.org/installation.html#editor-plugins
-.. _more: https://langserver.org/#implementations-client
+Apart from being a standalone tool, {program}`clang-tidy` is integrated into
+various IDEs, code analyzers, and editors. We recommend using [clangd][clangd] which
+integrates {program}`clang-tidy` and [is available][is available] in most major editors
+through plugins (Vim, Emacs, Visual Studio Code, Sublime Text and [more][more]).
 
-Apart from being a standalone tool, :program:`clang-tidy` is integrated into
-various IDEs, code analyzers, and editors. We recommend using clangd_ which
-integrates :program:`clang-tidy` and `is available`_ in most major editors
-through plugins (Vim, Emacs, Visual Studio Code, Sublime Text and more_).
-
-The following table shows the most well-known :program:`clang-tidy`
+The following table shows the most well-known {program}`clang-tidy`
 integrations in detail.
 
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|                                      |        Feature         |                                 |                          |                                         |                          |
-+======================================+========================+=================================+==========================+=========================================+==========================+
-|  **Tool**                            | On-the-fly inspection  | Check list configuration (GUI)  | Options to checks (GUI)  | Configuration via ``.clang-tidy`` files | Custom clang-tidy binary |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|A.L.E. for Vim                        |         \+\            |               \-\               |           \-\            |                 \-\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|Clang Power Tools for Visual Studio   |         \-\            |               \+\               |           \-\            |                 \+\                     |           \-\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|Clangd                                |         \+\            |               \-\               |           \-\            |                 \+\                     |           \-\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|CLion IDE                             |         \+\            |               \+\               |           \+\            |                 \+\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|CodeChecker                           |         \-\            |               \-\               |           \-\            |                 \-\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|CPPCheck                              |         \-\            |               \-\               |           \-\            |                 \-\                     |           \-\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|CPPDepend                             |         \-\            |               \-\               |           \-\            |                 \-\                     |           \-\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|Flycheck for Emacs                    |         \+\            |               \-\               |           \-\            |                 \+\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|KDevelop IDE                          |         \-\            |               \+\               |           \+\            |                 \+\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|Qt Creator IDE                        |         \+\            |               \+\               |           \-\            |                 \+\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|ReSharper C++ for Visual Studio       |         \+\            |               \+\               |           \-\            |                 \+\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|Syntastic for Vim                     |         \+\            |               \-\               |           \-\            |                 \-\                     |           \+\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
-|Visual Assist for Visual Studio       |         \+\            |               \+\               |           \-\            |                 \-\                     |           \-\            |
-+--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|                                     | Feature               |                                |                         |                                       |                          |
+| ----------------------------------- | --------------------- | ------------------------------ | ----------------------- | ------------------------------------- | ------------------------ |
+| **Tool**                            | On-the-fly inspection | Check list configuration (GUI) | Options to checks (GUI) | Configuration via `.clang-tidy` files | Custom clang-tidy binary |
+| A.L.E. for Vim                      | +                     | -                              | -                       | -                                     | +                        |
+| Clang Power Tools for Visual Studio | -                     | +                              | -                       | +                                     | -                        |
+| Clangd                              | +                     | -                              | -                       | +                                     | -                        |
+| CLion IDE                           | +                     | +                              | +                       | +                                     | +                        |
+| CodeChecker                         | -                     | -                              | -                       | -                                     | +                        |
+| CPPCheck                            | -                     | -                              | -                       | -                                     | -                        |
+| CPPDepend                           | -                     | -                              | -                       | -                                     | -                        |
+| Flycheck for Emacs                  | +                     | -                              | -                       | +                                     | +                        |
+| KDevelop IDE                        | -                     | +                              | +                       | +                                     | +                        |
+| Qt Creator IDE                      | +                     | +                              | -                       | +                                     | +                        |
+| ReSharper C++ for Visual Studio     | +                     | +                              | -                       | +                                     | +                        |
+| Syntastic for Vim                   | +                     | -                              | -                       | -                                     | +                        |
+| Visual Assist for Visual Studio     | +                     | +                              | -                       | -                                     | -                        |
 
 **IDEs**
 
-.. _CLion: https://www.jetbrains.com/clion/
-.. _integrates clang-tidy: https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html
-
-CLion_ 2017.2 and later `integrates clang-tidy`_ as an extension to the
+[CLion][clion] 2017.2 and later [integrates clang-tidy][integrates clang-tidy] as an extension to the
 built-in code analyzer. Starting from 2018.2 EAP, CLion allows using
-:program:`clang-tidy` via Clangd. Inspections and applicable quick-fixes are
+{program}`clang-tidy` via Clangd. Inspections and applicable quick-fixes are
 performed on the fly, and checks can be configured in standard command line
-format. In this integration, you can switch to the :program:`clang-tidy`
+format. In this integration, you can switch to the {program}`clang-tidy`
 binary different from the bundled one, pass the configuration in
-``.clang-tidy`` files instead of using the IDE settings, and configure
+`.clang-tidy` files instead of using the IDE settings, and configure
 options for particular checks.
 
-.. _KDevelop: https://www.kdevelop.org/
-.. _kdev-clang-tidy: https://github.com/KDE/kdev-clang-tidy/
-
-KDevelop_ with the kdev-clang-tidy_ plugin, starting from version 5.1, performs
-static analysis using :program:`clang-tidy`. The plugin launches the
-:program:`clang-tidy` binary from the specified location and parses its
+[KDevelop][kdevelop] with the [kdev-clang-tidy][kdev-clang-tidy] plugin, starting from version 5.1, performs
+static analysis using {program}`clang-tidy`. The plugin launches the
+{program}`clang-tidy` binary from the specified location and parses its
 output to provide a list of issues.
 
-.. _QtCreator: https://www.qt.io/
-.. _Clang Code Model: https://doc.qt.io/qtcreator/creator-clang-codemodel.html
-.. _Clang Tools: https://doc.qt.io/qtcreator/creator-clang-tools.html
-
-QtCreator_ 4.6 integrates :program:`clang-tidy` warnings into the editor
-diagnostics under the `Clang Code Model`_. To employ :program:`clang-tidy`
+[QtCreator][qtcreator] 4.6 integrates {program}`clang-tidy` warnings into the editor
+diagnostics under the [Clang Code Model][clang code model]. To employ {program}`clang-tidy`
 inspection in QtCreator, you need to create a copy of one of the presets and
 choose the checks to be performed. Since QtCreator 4.7 project-wide analysis is
-possible with the `Clang Tools`_ analyzer.
+possible with the [Clang Tools][clang tools] analyzer.
 
-.. _MS Visual Studio: https://visualstudio.microsoft.com/
-.. _ReSharper C++: https://www.jetbrains.com/help/resharper/Clang_Tidy_Integration.html
-.. _Visual Assist: https://docs.wholetomato.com/default.asp?W761
-.. _Clang Power Tools: https://marketplace.visualstudio.com/items?itemName=caphyon.ClangPowerTools
-
-`MS Visual Studio`_  can integrate :program:`clang-tidy` by means of three
-different tools. The `ReSharper C++`_ extension, version 2017.3 and later,
-provides seamless :program:`clang-tidy` integration: checks and quick-fixes run
+[MS Visual Studio][ms visual studio] can integrate {program}`clang-tidy` by means of three
+different tools. The [ReSharper C++][resharper c++] extension, version 2017.3 and later,
+provides seamless {program}`clang-tidy` integration: checks and quick-fixes run
 alongside native inspections.
-Apart from that, ReSharper C++ incorporates :program:`clang-tidy` as a separate
-step of its code clean-up process. `Visual Assist`_ build 2210 includes a
-subset of :program:`clang-tidy` checklist to inspect the code as you edit.
-Another way to bring :program:`clang-tidy` functionality to Visual Studio is
-the `Clang Power Tools`_ plugin, which includes most of the
-:program:`clang-tidy` checks and runs them during compilation or as a separate
+Apart from that, ReSharper C++ incorporates {program}`clang-tidy` as a separate
+step of its code clean-up process. [Visual Assist][visual assist] build 2210 includes a
+subset of {program}`clang-tidy` checklist to inspect the code as you edit.
+Another way to bring {program}`clang-tidy` functionality to Visual Studio is
+the [Clang Power Tools][clang power tools] plugin, which includes most of the
+{program}`clang-tidy` checks and runs them during compilation or as a separate
 step of code analysis.
 
 **Editors**
 
-.. _Flycheck: https://github.com/ch1bo/flycheck-clang-tidy
-.. _Syntastic: https://github.com/vim-syntastic/syntastic
-.. _A.L.E.: https://github.com/w0rp/ale
-.. _Emacs24: https://www.gnu.org/s/emacs/
-.. _Vim: https://www.vim.org/
-
-Emacs24_, when expanded with the Flycheck_ plugin, incorporates the
-:program:`clang-tidy` inspection into the syntax analyzer. For Vim_, you can
-use Syntastic_, which includes :program:`clang-tidy`, or `A.L.E.`_,
-a lint engine that applies :program:`clang-tidy` along with other linters.
+[Emacs24][emacs24], when expanded with the [Flycheck][flycheck] plugin, incorporates the
+{program}`clang-tidy` inspection into the syntax analyzer. For [Vim][vim], you can
+use [Syntastic][syntastic], which includes {program}`clang-tidy`, or [A.L.E.][a.l.e.],
+a lint engine that applies {program}`clang-tidy` along with other linters.
 
 **Analyzers**
 
-.. _CPPDepend: https://www.cppdepend.com/cppdependv2018
-.. _CPPCheck: https://sourceforge.net/p/cppcheck/news/
-.. _CodeChecker: https://github.com/Ericsson/codechecker
-.. _plugin: https://github.com/Ericsson/CodeCheckerEclipsePlugin
-
-:program:`clang-tidy` is integrated in CPPDepend_ starting from version 2018.1
-and CPPCheck_ 1.82. CPPCheck integration lets you import Visual Studio
-solutions and run the :program:`clang-tidy` inspection on them. The
-CodeChecker_ application of version 5.3 or later, which also comes as a plugin_
-for Eclipse, supports :program:`clang-tidy` as a static analysis instrument and
-allows to use a custom :program:`clang-tidy` binary.
+{program}`clang-tidy` is integrated in [CPPDepend][cppdepend] starting from version 2018.1
+and [CPPCheck][cppcheck] 1.82. CPPCheck integration lets you import Visual Studio
+solutions and run the {program}`clang-tidy` inspection on them. The
+[CodeChecker][codechecker] application of version 5.3 or later, which also comes as a [plugin][plugin]
+for Eclipse, supports {program}`clang-tidy` as a static analysis instrument and
+allows to use a custom {program}`clang-tidy` binary.
+
+[a.l.e.]: https://github.com/w0rp/ale
+[clang code model]: https://doc.qt.io/qtcreator/creator-clang-codemodel.html
+[clang power tools]: https://marketplace.visualstudio.com/items?itemName=caphyon.ClangPowerTools
+[clang tools]: https://doc.qt.io/qtcreator/creator-clang-tools.html
+[clangd]: http://clangd.llvm.org/
+[clion]: https://www.jetbrains.com/clion/
+[codechecker]: https://github.com/Ericsson/codechecker
+[cppcheck]: https://sourceforge.net/p/cppcheck/news/
+[cppdepend]: https://www.cppdepend.com/cppdependv2018
+[emacs24]: https://www.gnu.org/s/emacs/
+[flycheck]: https://github.com/ch1bo/flycheck-clang-tidy
+[integrates clang-tidy]: https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html
+[is available]: https://clangd.llvm.org/installation.html#editor-plugins
+[kdev-clang-tidy]: https://github.com/KDE/kdev-clang-tidy/
+[kdevelop]: https://www.kdevelop.org/
+[more]: https://langserver.org/#implementations-client
+[ms visual studio]: https://visualstudio.microsoft.com/
+[plugin]: https://github.com/Ericsson/CodeCheckerEclipsePlugin
+[qtcreator]: https://www.qt.io/
+[resharper c++]: https://www.jetbrains.com/help/resharper/Clang_Tidy_Integration.html
+[syntastic]: https://github.com/vim-syntastic/syntastic
+[vim]: https://www.vim.org/
+[visual assist]: https://docs.wholetomato.com/default.asp?W761
diff --git a/clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.md b/clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.md
index 966712682b4a3..6b97d5b7ee25f 100644
--- a/clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.md
+++ b/clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.md
@@ -1,14 +1,11 @@
-====================================
-Query Based Custom Clang-Tidy Checks
-====================================
+# Query Based Custom Clang-Tidy Checks
 
-Introduction
-============
+## Introduction
 
 This page provides examples of how to add query based custom checks for
-:program:`clang-tidy`.
+{program}`clang-tidy`.
 
-Custom checks are based on :program:`clang-query` syntax. Every custom checks
+Custom checks are based on {program}`clang-query` syntax. Every custom checks
 will be registered in `custom` module to avoid name conflict. They can be
 enabled or disabled by the checks option like the built-in checks.
 
@@ -19,62 +16,59 @@ Goals: easy to write, cross platform, multiple versions supported toolkit for
 custom clang-tidy rules.
 Non-Goals: complex checks, performance, fix-its, etc.
 
-Configuration
-=============
+## Configuration
 
 `CustomChecks` is a list of custom checks. Each check must contain
-  - Name: check name can be used in `-checks` option.
+: - Name: check name can be used in `-checks` option.
   - Query: `clang-query` string
   - Diagnostic: list of diagnostics to be reported.
-    - BindName: name of the node to be bound in `Query`.
-    - Message: message to be reported.
-    - Level: severity of the diagnostic, the possible values are
+    \- BindName: name of the node to be bound in `Query`.
+    \- Message: message to be reported.
+    \- Level: severity of the diagnostic, the possible values are
     `Note`, `Warning`.
 
 `CustomChecks` can be configured by `Checks` option in the configuration file.
 
-Example
-=======
-
-.. code-block:: yaml
-
-  Checks: -*,custom-call-main-function
-  CustomChecks:
-    - Name: call-main-function
-      Query: |
-          match callExpr(
-            callee(
-              functionDecl(isMain()).bind("fn")
-            )
-          ).bind("callee")
-      Diagnostic:
-        - BindName: fn
-          Message: main function.
-          Level: Note
-        - BindName: callee
-          Message: call to main function.
-          Level: Warning
-
-.. code-block:: c++
-
-  int main(); // note: main function.
-
-  void bar() {
-    main(); // warning: call to main function. [custom-call-main-function]
-  }
-
-Using with clangd
-=================
+## Example
+
+```yaml
+Checks: -*,custom-call-main-function
+CustomChecks:
+  - Name: call-main-function
+    Query: |
+        match callExpr(
+          callee(
+            functionDecl(isMain()).bind("fn")
+          )
+        ).bind("callee")
+    Diagnostic:
+      - BindName: fn
+        Message: main function.
+        Level: Note
+      - BindName: callee
+        Message: call to main function.
+        Level: Warning
+```
+
+```c++
+int main(); // note: main function.
+
+void bar() {
+  main(); // warning: call to main function. [custom-call-main-function]
+}
+```
+
+## Using with clangd
 
 To enable query-based custom checks in clangd, add the following to the clangd
 configuration:
 
-.. code-block:: yaml
-
-  Diagnostics:
-    ClangTidy:
-      ExperimentalCustomChecks: true
-      FastCheckFilter: Loose
+```yaml
+Diagnostics:
+  ClangTidy:
+    ExperimentalCustomChecks: true
+    FastCheckFilter: Loose
+```
 
 The custom-check definitions and check selection remain part of the clang-tidy
 configuration. `ExperimentalCustomChecks` does not override clangd's
@@ -82,21 +76,20 @@ configuration. `ExperimentalCustomChecks` does not override clangd's
 fast-check database, `Strict` excludes them, while `Loose` and `None`
 allow them.
 
-Matters Need Attention
-======================
+## Matters Need Attention
 
 This feature needs to be explicitly enabled by `--experimental-custom-checks`
 because it is currently in the experimental stage. Welcome to submit any
-suggestions in the `link <https://discourse.llvm.org/t/support-query-based-clang-tidy-external-check/85331>`_.
+suggestions in the [link](https://discourse.llvm.org/t/support-query-based-clang-tidy-external-check/85331).
 
 During the experimental stage, the required configuration structure of this
 feature may be changed in the future. Future changes will be as
 forward-compatible as possible, but this is not a guarantee.
 
 In subsequent versions, including non-experimental stage, the query statements
-will change at any time. The essence of :program:`clang-query` is to parse the
+will change at any time. The essence of {program}`clang-query` is to parse the
 query string and dynamically generate the corresponding AST matcher.
 Therefore, its functionality is entirely dependent on the functions provided by
 the AST matcher library.
 The ast matcher will change along with the changes in the clang AST.
-Please refer to `ast matcher reference <https://clang.llvm.org/docs/LibASTMatchersReference.html>`_.
+Please refer to [ast matcher reference](https://clang.llvm.org/docs/LibASTMatchersReference.html).
diff --git a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.md b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.md
index a00e476e06438..d6ca53a07875f 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.md
@@ -1,37 +1,37 @@
-.. title:: clang-tidy - llvmlibc-implementation-in-namespace
+```{title} clang-tidy - llvmlibc-implementation-in-namespace
+```
 
-llvmlibc-implementation-in-namespace
-====================================
+# llvmlibc-implementation-in-namespace
 
 Checks that all declarations in the llvm-libc implementation are within the
 correct namespace.
 
-.. code-block:: c++
-
-    // Implementation inside the LIBC_NAMESPACE_DECL namespace.
-    // Correct if:
-    // - LIBC_NAMESPACE_DECL is a macro
-    // - LIBC_NAMESPACE_DECL expansion starts with `[[gnu::visibility("hidden")]] __llvm_libc`
-    namespace LIBC_NAMESPACE_DECL {
-        LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
-        // Namespaces within LIBC_NAMESPACE_DECL namespace are allowed.
-        namespace inner {
-            int localVar = 0;
-        }
-        // Functions with C linkage are allowed.
-        extern "C" void str_fuzz() {}
+```c++
+// Implementation inside the LIBC_NAMESPACE_DECL namespace.
+// Correct if:
+// - LIBC_NAMESPACE_DECL is a macro
+// - LIBC_NAMESPACE_DECL expansion starts with `[[gnu::visibility("hidden")]] __llvm_libc`
+namespace LIBC_NAMESPACE_DECL {
+    LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
+    // Namespaces within LIBC_NAMESPACE_DECL namespace are allowed.
+    namespace inner {
+        int localVar = 0;
     }
+    // Functions with C linkage are allowed.
+    extern "C" void str_fuzz() {}
+}
 
-    // Incorrect: implementation not in the LIBC_NAMESPACE_DECL namespace.
-    LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
+// Incorrect: implementation not in the LIBC_NAMESPACE_DECL namespace.
+LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
 
-    // Incorrect: outer most namespace is not the LIBC_NAMESPACE_DECL macro.
-    namespace something_else {
-        LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
-    }
+// Incorrect: outer most namespace is not the LIBC_NAMESPACE_DECL macro.
+namespace something_else {
+    LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
+}
 
-    // Incorrect: outer most namespace expansion does not start with `[[gnu::visibility("hidden")]] __llvm_libc`.
-    #define LIBC_NAMESPACE_DECL custom_namespace
-    namespace LIBC_NAMESPACE_DECL {
-        LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
-    }
+// Incorrect: outer most namespace expansion does not start with `[[gnu::visibility("hidden")]] __llvm_libc`.
+#define LIBC_NAMESPACE_DECL custom_namespace
+namespace LIBC_NAMESPACE_DECL {
+    LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
index beda0e1665379..9336598f5f83f 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
@@ -1,35 +1,33 @@
-.. title:: clang-tidy - llvmlibc-restrict-system-libc-headers
+```{title} clang-tidy - llvmlibc-restrict-system-libc-headers
+```
 
-llvmlibc-restrict-system-libc-headers
-=====================================
+# llvmlibc-restrict-system-libc-headers
 
 Finds includes of system libc headers not provided by the compiler within
 llvm-libc implementations.
 
-.. code-block:: c++
-
-   #include <stdio.h>            // Not allowed because it is part of system libc.
-   #include <stddef.h>           // Allowed because it is provided by the compiler.
-   #include "internal/stdio.h"   // Allowed because it is NOT part of system libc.
-
+```c++
+#include <stdio.h>            // Not allowed because it is part of system libc.
+#include <stddef.h>           // Allowed because it is provided by the compiler.
+#include "internal/stdio.h"   // Allowed because it is NOT part of system libc.
+```
 
 This check is necessary because accidentally including system libc headers can
 lead to subtle and hard to detect bugs. For example consider a system libc
-whose ``dirent`` struct has slightly different field ordering than llvm-libc.
+whose `dirent` struct has slightly different field ordering than llvm-libc.
 While this will compile successfully, this can cause issues during runtime
 because they are ABI incompatible.
 
-Options
--------
-
-.. option:: Includes
+## Options
 
-   A string containing a comma separated glob list of allowed include
-   filenames. Similar to the -checks glob list for running clang-tidy itself,
-   the two wildcard characters are `*` and `-`, to include and exclude globs,
-   respectively. The default is `-*`, which disallows all includes.
+:::{option} Includes
+A string containing a comma separated glob list of allowed include
+filenames. Similar to the -checks glob list for running clang-tidy itself,
+the two wildcard characters are `*` and `-`, to include and exclude globs,
+respectively. The default is `-*`, which disallows all includes.
 
-   This can be used to allow known safe includes such as Linux development
-   headers. See :doc:`portability-restrict-system-includes
-   <../portability/restrict-system-includes>` for more
-   details.
+This can be used to allow known safe includes such as Linux development
+headers. See {doc}`portability-restrict-system-includes
+<../portability/restrict-system-includes>` for more
+details.
+:::
diff --git a/clang-tools-extra/docs/clang-tidy/index.md b/clang-tools-extra/docs/clang-tidy/index.md
index 9325307b6c9e4..719a283a04c07 100644
--- a/clang-tools-extra/docs/clang-tidy/index.md
+++ b/clang-tools-extra/docs/clang-tidy/index.md
@@ -1,442 +1,429 @@
-==========
-Clang-Tidy
-==========
+# Clang-Tidy
 
 See also:
 
-.. toctree::
-   :maxdepth: 1
+```{toctree}
+:maxdepth: 1
 
-   List of Clang-Tidy Checks <checks/list>
-   Query Based Custom Clang-Tidy Checks <QueryBasedCustomChecks>
-   Clang-tidy IDE/Editor Integrations <Integrations>
-   Getting Involved <Contributing>
-   External Clang-Tidy Examples <ExternalClang-TidyExamples>
+List of Clang-Tidy Checks <checks/list>
+Query Based Custom Clang-Tidy Checks <QueryBasedCustomChecks>
+Clang-tidy IDE/Editor Integrations <Integrations>
+Getting Involved <Contributing>
+External Clang-Tidy Examples <ExternalClang-TidyExamples>
+```
 
-:program:`clang-tidy` is a clang-based C++ "linter" tool. Its purpose is to
+{program}`clang-tidy` is a clang-based C++ "linter" tool. Its purpose is to
 provide an extensible framework for diagnosing and fixing typical programming
 errors, like style violations, interface misuse, or bugs that can be deduced
-via static analysis. :program:`clang-tidy` is modular and provides a
+via static analysis. {program}`clang-tidy` is modular and provides a
 convenient interface for writing new checks.
 
+## Using Clang-Tidy
 
-Using Clang-Tidy
-================
-
-:program:`clang-tidy` is a `LibTooling`_-based tool, and it's easier to work
+{program}`clang-tidy` is a [LibTooling][libtooling]-based tool, and it's easier to work
 with if you set up a compile command database for your project (for an example
-of how to do this, see `How To Setup Tooling For LLVM`_). You can also specify
-compilation options on the command line after ``--``:
-
-.. code-block:: console
+of how to do this, see [How To Setup Tooling For LLVM][how to setup tooling for llvm]). You can also specify
+compilation options on the command line after `--`:
 
-  $ clang-tidy test.cpp -- -Imy_project/include -DMY_DEFINES ...
+```console
+$ clang-tidy test.cpp -- -Imy_project/include -DMY_DEFINES ...
+```
 
 If there are too many options or source files to specify on the command line,
-you can store them in a parameter file, and use :program:`clang-tidy` with that
+you can store them in a parameter file, and use {program}`clang-tidy` with that
 parameters file:
 
-.. code-block:: console
-
-  $ clang-tidy @parameters_file
+```console
+$ clang-tidy @parameters_file
+```
 
-:program:`clang-tidy` has its own checks and can also run Clang Static Analyzer
+{program}`clang-tidy` has its own checks and can also run Clang Static Analyzer
 checks. Each check has a name and the checks to run can be chosen using the
-``-checks=`` option, which specifies a comma-separated list of positive and
-negative (prefixed with ``-``) globs. Positive globs add subsets of checks, and
+`-checks=` option, which specifies a comma-separated list of positive and
+negative (prefixed with `-`) globs. Positive globs add subsets of checks, and
 negative globs remove them. For example,
 
-.. code-block:: console
+```console
+$ clang-tidy test.cpp -checks=-*,clang-analyzer-*,-clang-analyzer-cplusplus*
+```
 
-  $ clang-tidy test.cpp -checks=-*,clang-analyzer-*,-clang-analyzer-cplusplus*
+will disable all default checks (`-*`) and enable all `clang-analyzer-*`
+checks except for `clang-analyzer-cplusplus*` ones.
 
-will disable all default checks (``-*``) and enable all ``clang-analyzer-*``
-checks except for ``clang-analyzer-cplusplus*`` ones.
-
-The ``-list-checks`` option lists all the enabled checks. When used without
-``-checks=``, it shows checks enabled by default. Use ``-checks=*`` to see all
-available checks or with any other value of ``-checks=`` to see which checks
+The `-list-checks` option lists all the enabled checks. When used without
+`-checks=`, it shows checks enabled by default. Use `-checks=*` to see all
+available checks or with any other value of `-checks=` to see which checks
 are enabled by this value.
 
-.. _checks-groups-table:
+(checks-groups-table)=
 
 There are currently the following groups of checks:
 
-====================== ========================================================
-Name prefix            Description
-====================== ========================================================
-``abseil-``            Checks related to Abseil library.
-``altera-``            Checks related to OpenCL programming for FPGAs.
-``android-``           Checks related to Android.
-``boost-``             Checks related to Boost library.
-``bugprone-``          Checks that target bug-prone code constructs.
-``cert-``              Checks related to CERT Secure Coding Guidelines.
-``clang-analyzer-``    Clang Static Analyzer checks.
-``concurrency-``       Checks related to concurrent programming (including
-                       threads, fibers, coroutines, etc.).
-``cppcoreguidelines-`` Checks related to C++ Core Guidelines.
-``darwin-``            Checks related to Darwin coding conventions.
-``fuchsia-``           Checks related to Fuchsia coding conventions.
-``google-``            Checks related to Google coding conventions.
-``linuxkernel-``       Checks related to the Linux Kernel coding conventions.
-``llvm-``              Checks related to the LLVM coding conventions.
-``llvmlibc-``          Checks related to the LLVM-libc coding standards.
-``misc-``              Checks that we didn't have a better category for.
-``modernize-``         Checks that advocate usage of modern (currently
-                       "modern" means "C++11") language constructs.
-``mpi-``               Checks related to MPI (Message Passing Interface).
-``objc-``              Checks related to Objective-C coding conventions.
-``openmp-``            Checks related to OpenMP API.
-``performance-``       Checks that target performance-related issues.
-``portability-``       Checks that target portability-related issues that
-                       don't relate to any particular coding style.
-``readability-``       Checks that target readability-related issues that
-                       don't relate to any particular coding style.
-====================== ========================================================
+| Name prefix          | Description                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| `abseil-`            | Checks related to Abseil library.                                                               |
+| `altera-`            | Checks related to OpenCL programming for FPGAs.                                                 |
+| `android-`           | Checks related to Android.                                                                      |
+| `boost-`             | Checks related to Boost library.                                                                |
+| `bugprone-`          | Checks that target bug-prone code constructs.                                                   |
+| `cert-`              | Checks related to CERT Secure Coding Guidelines.                                                |
+| `clang-analyzer-`    | Clang Static Analyzer checks.                                                                   |
+| `concurrency-`       | Checks related to concurrent programming (including threads, fibers, coroutines, etc.).         |
+| `cppcoreguidelines-` | Checks related to C++ Core Guidelines.                                                          |
+| `darwin-`            | Checks related to Darwin coding conventions.                                                    |
+| `fuchsia-`           | Checks related to Fuchsia coding conventions.                                                   |
+| `google-`            | Checks related to Google coding conventions.                                                    |
+| `linuxkernel-`       | Checks related to the Linux Kernel coding conventions.                                          |
+| `llvm-`              | Checks related to the LLVM coding conventions.                                                  |
+| `llvmlibc-`          | Checks related to the LLVM-libc coding standards.                                               |
+| `misc-`              | Checks that we didn't have a better category for.                                               |
+| `modernize-`         | Checks that advocate usage of modern (currently "modern" means "C++11") language constructs.    |
+| `mpi-`               | Checks related to MPI (Message Passing Interface).                                              |
+| `objc-`              | Checks related to Objective-C coding conventions.                                               |
+| `openmp-`            | Checks related to OpenMP API.                                                                   |
+| `performance-`       | Checks that target performance-related issues.                                                  |
+| `portability-`       | Checks that target portability-related issues that don't relate to any particular coding style. |
+| `readability-`       | Checks that target readability-related issues that don't relate to any particular coding style. |
 
 Clang diagnostics are treated in a similar way as check diagnostics. Clang
-diagnostics are displayed by :program:`clang-tidy` and can be filtered out
-using the ``-checks=`` option. However, the ``-checks=`` option does not
+diagnostics are displayed by {program}`clang-tidy` and can be filtered out
+using the `-checks=` option. However, the `-checks=` option does not
 affect compilation arguments, so it cannot turn on Clang warnings which are
-not already turned on in the build configuration. The ``-warnings-as-errors=``
-option upgrades any warnings emitted under the ``-checks=`` flag to errors (but
+not already turned on in the build configuration. The `-warnings-as-errors=`
+option upgrades any warnings emitted under the `-checks=` flag to errors (but
 it does not enable any checks itself).
 
-Clang diagnostics have check names starting with ``clang-diagnostic-``.
+Clang diagnostics have check names starting with `clang-diagnostic-`.
 Diagnostics which have a corresponding warning option, are named
-``clang-diagnostic-<warning-option>``, e.g. Clang warning controlled by
-``-Wliteral-conversion`` will be reported with check name
-``clang-diagnostic-literal-conversion``.
+`clang-diagnostic-<warning-option>`, e.g. Clang warning controlled by
+`-Wliteral-conversion` will be reported with check name
+`clang-diagnostic-literal-conversion`.
 
 Clang compiler errors (such as syntax errors, semantic errors, or other
 failures that prevent Clang from compiling the code) are reported with the
-check name ``clang-diagnostic-error``. These represent fundamental compilation
-failures that must be fixed before :program:`clang-tidy` can perform its
-analysis. Unlike other diagnostics, ``clang-diagnostic-error`` cannot be
-disabled, as :program:`clang-tidy` requires valid code to function.
+check name `clang-diagnostic-error`. These represent fundamental compilation
+failures that must be fixed before {program}`clang-tidy` can perform its
+analysis. Unlike other diagnostics, `clang-diagnostic-error` cannot be
+disabled, as {program}`clang-tidy` requires valid code to function.
 
-The ``-fix`` flag instructs :program:`clang-tidy` to fix found errors if
+The `-fix` flag instructs {program}`clang-tidy` to fix found errors if
 supported by corresponding checks.
 
 An overview of all the command-line options:
 
-.. code-block:: console
-
-  $ clang-tidy --help
-  USAGE: clang-tidy [options] <source0> [... <sourceN>]
-
-  OPTIONS:
-
-  Generic Options:
-
-    --help                           - Display available options (--help-hidden for more)
-    --help-list                      - Display list of available options (--help-list-hidden for more)
-    --version                        - Display the version of this program
-
-  clang-tidy options:
-
-    --allow-no-checks                - Allow empty enabled checks. This suppresses
-                                       the "no checks enabled" error when disabling
-                                       all of the checks.
-    --checks=<string>                - Comma-separated list of globs with optional '-'
-                                       prefix. Globs are processed in order of
-                                       appearance in the list. Globs without '-'
-                                       prefix add checks with matching names to the
-                                       set, globs with the '-' prefix remove checks
-                                       with matching names from the set of enabled
-                                       checks. This option's value is appended to the
-                                       value of the 'Checks' option in .clang-tidy
-                                       file, if any.
-    --config=<string>                - Specifies a configuration in YAML/JSON format:
-                                         -config="{Checks: '*',
-                                                   CheckOptions: {x: y}}"
-                                       When the value is empty, clang-tidy will
-                                       attempt to find a file named .clang-tidy for
-                                       each source file in its parent directories.
-    --config-file=<string>           - Specify the path of .clang-tidy or custom config file:
-                                        e.g. --config-file=/some/path/myTidyConfigFile
-                                       This option internally works exactly the same way as
-                                        --config option after reading specified config file.
-                                       Use either --config-file or --config, not both.
-    --dump-config                    - Dumps configuration in the YAML format to
-                                       stdout. This option can be used along with a
-                                       file name (and '--' if the file is outside of a
-                                       project with configured compilation database).
-                                       The configuration used for this file will be
-                                       printed.
-                                       Use along with -checks=* to include
-                                       configuration of all checks.
-    --enable-check-profile           - Enable per-check timing profiles, and print a
-                                       report to stderr.
-    --enable-module-headers-parsing  - Enables preprocessor-level module header parsing
-                                       for C++20 and above, empowering specific checks
-                                       to detect macro definitions within modules. This
-                                       feature may cause performance and parsing issues
-                                       and is therefore considered experimental.
-    --exclude-header-filter=<string> - Regular expression matching the names of the
-                                       headers to exclude diagnostics from. Diagnostics
-                                       from the main file of each translation unit are
-                                       always displayed.
-                                       Must be used together with --header-filter.
-                                       Can be used together with -line-filter.
-                                       This option overrides the 'ExcludeHeaderFilterRegex'
-                                       option in .clang-tidy file, if any.
-    --experimental-custom-checks     - Enable experimental clang-query based
-                                       custom checks.
-                                       see https://clang.llvm.org/extra/clang-tidy/QueryBasedCustomChecks.html.
-    --explain-config                 - For each enabled check explains, where it is
-                                       enabled, i.e. in clang-tidy binary, command
-                                       line or a specific configuration file.
-    --export-fixes=<filename>        - YAML file to store suggested fixes in. The
-                                       stored fixes can be applied to the input source
-                                       code with clang-apply-replacements.
-    --extra-arg=<string>             - Additional argument to append to the compiler command line
-    --extra-arg-before=<string>      - Additional argument to prepend to the compiler command line
-    --fix                            - Apply suggested fixes. Without -fix-errors
-                                       clang-tidy will bail out if any compilation
-                                       errors were found.
-    --fix-errors                     - Apply suggested fixes even if compilation
-                                       errors were found. If compiler errors have
-                                       attached fix-its, clang-tidy will apply them as
-                                       well.
-    --fix-notes                      - If a warning has no fix, but a single fix can
-                                       be found through an associated diagnostic note,
-                                       apply the fix.
-                                       Specifying this flag will implicitly enable the
-                                       '--fix' flag.
-    --format-style=<string>          - Style for formatting code around applied fixes:
-                                         - 'none' (default) turns off formatting
-                                         - 'file' (literally 'file', not a placeholder)
-                                           uses .clang-format file in the closest parent
-                                           directory
-                                         - '{ <json> }' specifies options inline, e.g.
-                                           -format-style='{BasedOnStyle: llvm, IndentWidth: 8}'
-                                         - 'llvm', 'google', 'webkit', 'mozilla'
-                                       See clang-format documentation for the up-to-date
-                                       information about formatting styles and options.
-                                       This option overrides the 'FormatStyle` option in
-                                       .clang-tidy file, if any.
-    --header-filter=<string>         - Regular expression matching the names of the
-                                       headers to output diagnostics from. The default
-                                       value is '.*', i.e. diagnostics from all non-system
-                                       headers are displayed by default. Diagnostics
-                                       from the main file of each translation unit are
-                                       always displayed.
-                                       Can be used together with -line-filter.
-                                       This option overrides the 'HeaderFilterRegex'
-                                       option in .clang-tidy file, if any.
-    --line-filter=<string>           - List of files and line ranges to output diagnostics from.
-                                       The range is inclusive on both ends. Can be used together
-                                       with -header-filter. The format of the list is a JSON
-                                       array of objects. For example:
-
-                                         [
-                                           {"name":"file1.cpp","lines":[[1,3],[5,7]]},
-                                           {"name":"file2.h"}
-                                         ]
-
-                                       This will output diagnostics from 'file1.cpp' only for
-                                       the line ranges [1,3] and [5,7], as well as all from the
-                                       entire 'file2.h'.
-    --list-checks                    - List all enabled checks and exit. Use with
-                                       -checks=* to list all available checks.
-    --load=<pluginfilename>          - Load the specified plugin
-    -p <string>                      - Build path
-    --quiet                          - Run clang-tidy in quiet mode. This suppresses
-                                       printing statistics about ignored warnings and
-                                       warnings treated as errors if the respective
-                                       options are specified.
-    --removed-arg=<string>           - List of arguments to remove from the command
-                                       line sent to the compiler. Please note that
-                                       removing arguments might change the semantic
-                                       of the analyzed code, possibly leading to
-                                       compiler errors, false positives or
-                                       false negatives. This option is applied
-                                       before --extra-arg and --extra-arg-before
-    --store-check-profile=<prefix>   - By default reports are printed in tabulated
-                                       format to stderr. When this option is passed,
-                                       these per-TU profiles are instead stored as JSON.
-    --system-headers                 - Display the errors from system headers.
-                                       This option overrides the 'SystemHeaders' option
-                                       in .clang-tidy file, if any.
-    --use-color                      - Use colors in diagnostics. If not set, colors
-                                       will be used if the terminal connected to
-                                       standard output supports colors.
-                                       This option overrides the 'UseColor' option in
-                                       .clang-tidy file, if any.
-    --verify-config                  - Check the config files to ensure each check and
-                                       option is recognized without running any checks.
-    --vfsoverlay=<filename>          - Overlay the virtual filesystem described by file
-                                       over the real file system.
-    --warnings-as-errors=<string>    - Upgrades warnings to errors. Same format as
-                                       '-checks'.
-                                       This option's value is appended to the value of
-                                       the 'WarningsAsErrors' option in .clang-tidy
-                                       file, if any.
-
-  -p <build-path> is used to read a compile command database.
-
-    For example, it can be a CMake build directory in which a file named
-    compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-    CMake option to get this output). When no build path is specified,
-    a search for compile_commands.json will be attempted through all
-    parent paths of the first input file . See:
-    https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an
-    example of setting up Clang Tooling on a source tree.
-
-  <source0> ... specify the paths of source files. These paths are
-    looked up in the compile command database. If the path of a file is
-    absolute, it needs to point into CMake's source tree. If the path is
-    relative, the current working directory needs to be in the CMake
-    source tree and the file must be in a subdirectory of the current
-    working directory. "./" prefixes in the relative files will be
-    automatically removed, but the rest of a relative path must be a
-    suffix of a path in the compile command database.
-
-  Parameters files:
-    A large number of options or source files can be passed as parameter files
-    by use '@parameter-file' in the command line.
-
-  Configuration files:
-    clang-tidy attempts to read configuration for each source file from a
-    .clang-tidy file located in the closest parent directory of the source
-    file. The .clang-tidy file is specified in YAML format. If any configuration
-    options have a corresponding command-line option, command-line option takes
-    precedence.
-
-    The following configuration options may be used in a .clang-tidy file:
-
-    CheckOptions                 - List of key-value pairs defining check-specific
-                                   options. Example:
-                                     CheckOptions:
-                                       some-check.SomeOption: 'some value'
-    Checks                       - Same as '--checks'. Additionally, the list of
-                                   globs can be specified as a list instead of a
-                                   string.
-    CustomChecks                 - Array of user defined checks based on
-                                   Clang-Query syntax.
-    ExcludeHeaderFilterRegex     - Same as '--exclude-header-filter'.
-    ExtraArgs                    - Same as '--extra-arg'.
-    ExtraArgsBefore              - Same as '--extra-arg-before'.
-    FormatStyle                  - Same as '--format-style'.
-    HeaderFileExtensions         - File extensions to consider to determine if a
-                                   given diagnostic is located in a header file.
-    HeaderFilterRegex            - Same as '--header-filter'.
-    ImplementationFileExtensions - File extensions to consider to determine if a
-                                   given diagnostic is located in an
-                                   implementation file.
-    InheritParentConfig          - If this option is true in a config file, the
-                                   configuration file in the parent directory
-                                   (if any exists) will be taken and the current
-                                   config file will be applied on top of the
-                                   parent one.
-    RemovedArgs                  - Same as '--removed-arg'.
-    SystemHeaders                - Same as '--system-headers'.
-    UseColor                     - Same as '--use-color'.
-    User                         - Specifies the name or e-mail of the user
-                                   running clang-tidy. This option is used, for
-                                   example, to place the correct user name in
-                                   TODO() comments in the relevant check.
-    WarningsAsErrors             - Same as '--warnings-as-errors'.
-
-    The effective configuration can be inspected using --dump-config:
-
-      $ clang-tidy --dump-config
-      ---
-      Checks:                       '-*,some-check'
-      WarningsAsErrors:             ''
-      HeaderFileExtensions:         ['', 'h','hh','hpp','hxx']
-      ImplementationFileExtensions: ['c','cc','cpp','cxx']
-      HeaderFilterRegex:            '.*'
-      FormatStyle:                  none
-      InheritParentConfig:          true
-      User:                         user
-      CheckOptions:
-        some-check.SomeOption: 'some value'
-      ...
-
-Running Clang-Tidy on CUDA Files
---------------------------------
-
-:program:`clang-tidy` supports analyzing CUDA source files. To ensure correct
+```console
+$ clang-tidy --help
+USAGE: clang-tidy [options] <source0> [... <sourceN>]
+
+OPTIONS:
+
+Generic Options:
+
+  --help                           - Display available options (--help-hidden for more)
+  --help-list                      - Display list of available options (--help-list-hidden for more)
+  --version                        - Display the version of this program
+
+clang-tidy options:
+
+  --allow-no-checks                - Allow empty enabled checks. This suppresses
+                                     the "no checks enabled" error when disabling
+                                     all of the checks.
+  --checks=<string>                - Comma-separated list of globs with optional '-'
+                                     prefix. Globs are processed in order of
+                                     appearance in the list. Globs without '-'
+                                     prefix add checks with matching names to the
+                                     set, globs with the '-' prefix remove checks
+                                     with matching names from the set of enabled
+                                     checks. This option's value is appended to the
+                                     value of the 'Checks' option in .clang-tidy
+                                     file, if any.
+  --config=<string>                - Specifies a configuration in YAML/JSON format:
+                                       -config="{Checks: '*',
+                                                 CheckOptions: {x: y}}"
+                                     When the value is empty, clang-tidy will
+                                     attempt to find a file named .clang-tidy for
+                                     each source file in its parent directories.
+  --config-file=<string>           - Specify the path of .clang-tidy or custom config file:
+                                      e.g. --config-file=/some/path/myTidyConfigFile
+                                     This option internally works exactly the same way as
+                                      --config option after reading specified config file.
+                                     Use either --config-file or --config, not both.
+  --dump-config                    - Dumps configuration in the YAML format to
+                                     stdout. This option can be used along with a
+                                     file name (and '--' if the file is outside of a
+                                     project with configured compilation database).
+                                     The configuration used for this file will be
+                                     printed.
+                                     Use along with -checks=* to include
+                                     configuration of all checks.
+  --enable-check-profile           - Enable per-check timing profiles, and print a
+                                     report to stderr.
+  --enable-module-headers-parsing  - Enables preprocessor-level module header parsing
+                                     for C++20 and above, empowering specific checks
+                                     to detect macro definitions within modules. This
+                                     feature may cause performance and parsing issues
+                                     and is therefore considered experimental.
+  --exclude-header-filter=<string> - Regular expression matching the names of the
+                                     headers to exclude diagnostics from. Diagnostics
+                                     from the main file of each translation unit are
+                                     always displayed.
+                                     Must be used together with --header-filter.
+                                     Can be used together with -line-filter.
+                                     This option overrides the 'ExcludeHeaderFilterRegex'
+                                     option in .clang-tidy file, if any.
+  --experimental-custom-checks     - Enable experimental clang-query based
+                                     custom checks.
+                                     see https://clang.llvm.org/extra/clang-tidy/QueryBasedCustomChecks.html.
+  --explain-config                 - For each enabled check explains, where it is
+                                     enabled, i.e. in clang-tidy binary, command
+                                     line or a specific configuration file.
+  --export-fixes=<filename>        - YAML file to store suggested fixes in. The
+                                     stored fixes can be applied to the input source
+                                     code with clang-apply-replacements.
+  --extra-arg=<string>             - Additional argument to append to the compiler command line
+  --extra-arg-before=<string>      - Additional argument to prepend to the compiler command line
+  --fix                            - Apply suggested fixes. Without -fix-errors
+                                     clang-tidy will bail out if any compilation
+                                     errors were found.
+  --fix-errors                     - Apply suggested fixes even if compilation
+                                     errors were found. If compiler errors have
+                                     attached fix-its, clang-tidy will apply them as
+                                     well.
+  --fix-notes                      - If a warning has no fix, but a single fix can
+                                     be found through an associated diagnostic note,
+                                     apply the fix.
+                                     Specifying this flag will implicitly enable the
+                                     '--fix' flag.
+  --format-style=<string>          - Style for formatting code around applied fixes:
+                                       - 'none' (default) turns off formatting
+                                       - 'file' (literally 'file', not a placeholder)
+                                         uses .clang-format file in the closest parent
+                                         directory
+                                       - '{ <json> }' specifies options inline, e.g.
+                                         -format-style='{BasedOnStyle: llvm, IndentWidth: 8}'
+                                       - 'llvm', 'google', 'webkit', 'mozilla'
+                                     See clang-format documentation for the up-to-date
+                                     information about formatting styles and options.
+                                     This option overrides the 'FormatStyle` option in
+                                     .clang-tidy file, if any.
+  --header-filter=<string>         - Regular expression matching the names of the
+                                     headers to output diagnostics from. The default
+                                     value is '.*', i.e. diagnostics from all non-system
+                                     headers are displayed by default. Diagnostics
+                                     from the main file of each translation unit are
+                                     always displayed.
+                                     Can be used together with -line-filter.
+                                     This option overrides the 'HeaderFilterRegex'
+                                     option in .clang-tidy file, if any.
+  --line-filter=<string>           - List of files and line ranges to output diagnostics from.
+                                     The range is inclusive on both ends. Can be used together
+                                     with -header-filter. The format of the list is a JSON
+                                     array of objects. For example:
+
+                                       [
+                                         {"name":"file1.cpp","lines":[[1,3],[5,7]]},
+                                         {"name":"file2.h"}
+                                       ]
+
+                                     This will output diagnostics from 'file1.cpp' only for
+                                     the line ranges [1,3] and [5,7], as well as all from the
+                                     entire 'file2.h'.
+  --list-checks                    - List all enabled checks and exit. Use with
+                                     -checks=* to list all available checks.
+  --load=<pluginfilename>          - Load the specified plugin
+  -p <string>                      - Build path
+  --quiet                          - Run clang-tidy in quiet mode. This suppresses
+                                     printing statistics about ignored warnings and
+                                     warnings treated as errors if the respective
+                                     options are specified.
+  --removed-arg=<string>           - List of arguments to remove from the command
+                                     line sent to the compiler. Please note that
+                                     removing arguments might change the semantic
+                                     of the analyzed code, possibly leading to
+                                     compiler errors, false positives or
+                                     false negatives. This option is applied
+                                     before --extra-arg and --extra-arg-before
+  --store-check-profile=<prefix>   - By default reports are printed in tabulated
+                                     format to stderr. When this option is passed,
+                                     these per-TU profiles are instead stored as JSON.
+  --system-headers                 - Display the errors from system headers.
+                                     This option overrides the 'SystemHeaders' option
+                                     in .clang-tidy file, if any.
+  --use-color                      - Use colors in diagnostics. If not set, colors
+                                     will be used if the terminal connected to
+                                     standard output supports colors.
+                                     This option overrides the 'UseColor' option in
+                                     .clang-tidy file, if any.
+  --verify-config                  - Check the config files to ensure each check and
+                                     option is recognized without running any checks.
+  --vfsoverlay=<filename>          - Overlay the virtual filesystem described by file
+                                     over the real file system.
+  --warnings-as-errors=<string>    - Upgrades warnings to errors. Same format as
+                                     '-checks'.
+                                     This option's value is appended to the value of
+                                     the 'WarningsAsErrors' option in .clang-tidy
+                                     file, if any.
+
+-p <build-path> is used to read a compile command database.
+
+  For example, it can be a CMake build directory in which a file named
+  compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+  CMake option to get this output). When no build path is specified,
+  a search for compile_commands.json will be attempted through all
+  parent paths of the first input file . See:
+  https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an
+  example of setting up Clang Tooling on a source tree.
+
+<source0> ... specify the paths of source files. These paths are
+  looked up in the compile command database. If the path of a file is
+  absolute, it needs to point into CMake's source tree. If the path is
+  relative, the current working directory needs to be in the CMake
+  source tree and the file must be in a subdirectory of the current
+  working directory. "./" prefixes in the relative files will be
+  automatically removed, but the rest of a relative path must be a
+  suffix of a path in the compile command database.
+
+Parameters files:
+  A large number of options or source files can be passed as parameter files
+  by use '@parameter-file' in the command line.
+
+Configuration files:
+  clang-tidy attempts to read configuration for each source file from a
+  .clang-tidy file located in the closest parent directory of the source
+  file. The .clang-tidy file is specified in YAML format. If any configuration
+  options have a corresponding command-line option, command-line option takes
+  precedence.
+
+  The following configuration options may be used in a .clang-tidy file:
+
+  CheckOptions                 - List of key-value pairs defining check-specific
+                                 options. Example:
+                                   CheckOptions:
+                                     some-check.SomeOption: 'some value'
+  Checks                       - Same as '--checks'. Additionally, the list of
+                                 globs can be specified as a list instead of a
+                                 string.
+  CustomChecks                 - Array of user defined checks based on
+                                 Clang-Query syntax.
+  ExcludeHeaderFilterRegex     - Same as '--exclude-header-filter'.
+  ExtraArgs                    - Same as '--extra-arg'.
+  ExtraArgsBefore              - Same as '--extra-arg-before'.
+  FormatStyle                  - Same as '--format-style'.
+  HeaderFileExtensions         - File extensions to consider to determine if a
+                                 given diagnostic is located in a header file.
+  HeaderFilterRegex            - Same as '--header-filter'.
+  ImplementationFileExtensions - File extensions to consider to determine if a
+                                 given diagnostic is located in an
+                                 implementation file.
+  InheritParentConfig          - If this option is true in a config file, the
+                                 configuration file in the parent directory
+                                 (if any exists) will be taken and the current
+                                 config file will be applied on top of the
+                                 parent one.
+  RemovedArgs                  - Same as '--removed-arg'.
+  SystemHeaders                - Same as '--system-headers'.
+  UseColor                     - Same as '--use-color'.
+  User                         - Specifies the name or e-mail of the user
+                                 running clang-tidy. This option is used, for
+                                 example, to place the correct user name in
+                                 TODO() comments in the relevant check.
+  WarningsAsErrors             - Same as '--warnings-as-errors'.
+
+  The effective configuration can be inspected using --dump-config:
+
+    $ clang-tidy --dump-config
+    ---
+    Checks:                       '-*,some-check'
+    WarningsAsErrors:             ''
+    HeaderFileExtensions:         ['', 'h','hh','hpp','hxx']
+    ImplementationFileExtensions: ['c','cc','cpp','cxx']
+    HeaderFilterRegex:            '.*'
+    FormatStyle:                  none
+    InheritParentConfig:          true
+    User:                         user
+    CheckOptions:
+      some-check.SomeOption: 'some value'
+    ...
+```
+
+### Running Clang-Tidy on CUDA Files
+
+{program}`clang-tidy` supports analyzing CUDA source files. To ensure correct
 header resolution, it is important to specify the CUDA toolkit path using
-``--cuda-path``. For more details on how Clang handles CUDA, see
-`Compiling CUDA with Clang <https://llvm.org/docs/CompileCudaWithLLVM.html>`_.
+`--cuda-path`. For more details on how Clang handles CUDA, see
+[Compiling CUDA with Clang](https://llvm.org/docs/CompileCudaWithLLVM.html).
 
 If you are using a GCC + NVCC build setup, the compiler command database will
-contain NVCC-specific flags that :program:`clang-tidy` does not understand.
+contain NVCC-specific flags that {program}`clang-tidy` does not understand.
 
-In this case, you should use the ``RemovedArgs`` configuration option (or
-``--removed-arg`` command-line option) to remove these flags, and
-``ExtraArgs`` (or ``--extra-arg``) to provide the ``--cuda-path``.
+In this case, you should use the `RemovedArgs` configuration option (or
+`--removed-arg` command-line option) to remove these flags, and
+`ExtraArgs` (or `--extra-arg`) to provide the `--cuda-path`.
 
-For example, to remove the NVCC-specific ``-gencode`` flag and provide the
+For example, to remove the NVCC-specific `-gencode` flag and provide the
 CUDA path:
 
-.. code-block:: console
-
-  $ clang-tidy source.cu --removed-arg="-gencode" --removed-arg="arch=.." --extra-arg="--cuda-path=/path/to/cuda"
+```console
+$ clang-tidy source.cu --removed-arg="-gencode" --removed-arg="arch=.." --extra-arg="--cuda-path=/path/to/cuda"
+```
 
-By default, :program:`clang-tidy` will analyze both host and device code.
+By default, {program}`clang-tidy` will analyze both host and device code.
 To restrict the analysis to a specific side and specifically choose device
-compilation flags, use the ``--extra-arg`` flag to pass the arguments.
+compilation flags, use the `--extra-arg` flag to pass the arguments.
 
 For example, to perform device analysis only, use
-the ``--cuda-device-only`` flag:
+the `--cuda-device-only` flag:
 
-.. code-block:: console
+```console
+$ clang-tidy source.cu --extra-arg="--cuda-device-only" --extra-arg="--cuda-path=/path/to/cuda"
+```
 
-  $ clang-tidy source.cu --extra-arg="--cuda-device-only" --extra-arg="--cuda-path=/path/to/cuda"
+## Clang-Tidy Automation
 
-Clang-Tidy Automation
-=====================
-
-:program:`clang-tidy` can analyze multiple source files by specifying them on
+{program}`clang-tidy` can analyze multiple source files by specifying them on
 the command line. For larger projects, automation scripts provide additional
 functionality like parallel execution and integration with version control
 systems.
 
-Running Clang-Tidy in Parallel
--------------------------------
+### Running Clang-Tidy in Parallel
 
-:program:`clang-tidy` can process multiple files sequentially, but for projects
-with many source files, the :program:`run-clang-tidy.py` script provides
+{program}`clang-tidy` can process multiple files sequentially, but for projects
+with many source files, the {program}`run-clang-tidy.py` script provides
 parallel execution to significantly reduce analysis time. This script is
-included with clang-tidy and runs :program:`clang-tidy` over all files in a
+included with clang-tidy and runs {program}`clang-tidy` over all files in a
 compilation database or a specified path concurrently.
 
-The script requires a compilation database (``compile_commands.json``) which
+The script requires a compilation database (`compile_commands.json`) which
 can be generated by build systems like CMake (using
-``-DCMAKE_EXPORT_COMPILE_COMMANDS=ON``) or by tools like `Bear`_.
+`-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) or by tools like [Bear][bear].
 
-The script supports most of the same options as :program:`clang-tidy` itself,
-including ``-checks=``, ``-fix``, ``-header-filter=``, and configuration
-options. Run ``run-clang-tidy.py --help`` for a complete list of available
+The script supports most of the same options as {program}`clang-tidy` itself,
+including `-checks=`, `-fix`, `-header-filter=`, and configuration
+options. Run `run-clang-tidy.py --help` for a complete list of available
 options.
 
 Example invocations:
 
-.. code-block:: console
-
-  # Run clang-tidy on all files in the compilation database in parallel
-  $ run-clang-tidy.py -p=build/
+```console
+# Run clang-tidy on all files in the compilation database in parallel
+$ run-clang-tidy.py -p=build/
 
-  # Run with specific checks and apply fixes
-  $ run-clang-tidy.py -p=build/ -fix -checks=-*,readability-*
+# Run with specific checks and apply fixes
+$ run-clang-tidy.py -p=build/ -fix -checks=-*,readability-*
 
-  # Run on specific files/directories with header filtering
-  $ run-clang-tidy.py -p=build/ -header-filter=src/ src/
+# Run on specific files/directories with header filtering
+$ run-clang-tidy.py -p=build/ -header-filter=src/ src/
 
-  # Run with parallel execution (uses all CPU cores by default)
-  $ run-clang-tidy.py -p=build/ -j 4
+# Run with parallel execution (uses all CPU cores by default)
+$ run-clang-tidy.py -p=build/ -j 4
+```
 
-Running Clang-Tidy on Diff
----------------------------
+### Running Clang-Tidy on Diff
 
-The :program:`clang-tidy-diff.py` script allows you to run
-:program:`clang-tidy` on the lines that have been modified in your working
-directory or in a specific diff. Importantly, :program:`clang-tidy-diff.py` only reports
-diagnostics for changed lines; :program:`clang-tidy` still analyzes the entire
+The {program}`clang-tidy-diff.py` script allows you to run
+{program}`clang-tidy` on the lines that have been modified in your working
+directory or in a specific diff. Importantly, {program}`clang-tidy-diff.py` only reports
+diagnostics for changed lines; {program}`clang-tidy` still analyzes the entire
 file and filters out unchanged lines after analysis, so this does not improve
 performance. This is particularly useful for code reviews and continuous
 integration, as it focuses analysis on the changed code rather than the entire
@@ -444,80 +431,77 @@ codebase.
 
 The script can work with various diff sources:
 
-* Git working directory changes
-* Output from ``git diff``
-* Output from ``svn diff``
-* Patch files
+- Git working directory changes
+- Output from `git diff`
+- Output from `svn diff`
+- Patch files
 
 Example invocations:
 
-.. code-block:: console
+```console
+# Run clang-tidy on all changes in the working directory
+$ git diff -U0 --no-color HEAD^ | clang-tidy-diff.py -p1
 
-  # Run clang-tidy on all changes in the working directory
-  $ git diff -U0 --no-color HEAD^ | clang-tidy-diff.py -p1
+# Run with specific checks and apply fixes
+$ git diff -U0 --no-color HEAD^ | clang-tidy-diff.py -p1 -fix \
+  -checks=-*,readability-*
 
-  # Run with specific checks and apply fixes
-  $ git diff -U0 --no-color HEAD^ | clang-tidy-diff.py -p1 -fix \
-    -checks=-*,readability-*
+# Run on staged changes
+$ git diff -U0 --no-color --cached | clang-tidy-diff.py -p1
 
-  # Run on staged changes
-  $ git diff -U0 --no-color --cached | clang-tidy-diff.py -p1
+# Run on changes between two commits
+$ git diff -U0 --no-color HEAD~2 HEAD | clang-tidy-diff.py -p1
 
-  # Run on changes between two commits
-  $ git diff -U0 --no-color HEAD~2 HEAD | clang-tidy-diff.py -p1
+# Run on a patch file
+$ clang-tidy-diff.py -p1 < changes.patch
+```
 
-  # Run on a patch file
-  $ clang-tidy-diff.py -p1 < changes.patch
-
-The ``-p1`` option tells the script to strip one level of path prefix from
+The `-p1` option tells the script to strip one level of path prefix from
 the diff, which is typically needed for Git diffs. The script supports most of
-the same options as :program:`clang-tidy` itself, including ``-checks=``,
-``-fix``, ``-header-filter=``, and configuration options.
+the same options as {program}`clang-tidy` itself, including `-checks=`,
+`-fix`, `-header-filter=`, and configuration options.
 
-While :program:`clang-tidy-diff.py` is useful for focusing on recent changes,
+While {program}`clang-tidy-diff.py` is useful for focusing on recent changes,
 relying solely on it may lead to incomplete analysis. Since the script only
 reports warnings from the modified lines, it may miss issues that are caused
 by the changes but manifest elsewhere in the code. For example, changes that
 only add lines to a function may cause it to violate size limits (e.g.,
-`readability-function-size <checks/readability/function-size.html>`_), but the
+[readability-function-size](checks/readability/function-size.md)), but the
 diagnostic will be reported at the function declaration, which may not be in
 the diff and thus filtered out. Modifications to header files may also affect
 many implementation files, but only warnings in the modified header lines will
 be reported.
 
 For comprehensive analysis, especially before merging significant changes,
-consider running :program:`clang-tidy` on the entire affected files or the
-whole project using :program:`run-clang-tidy.py`.
+consider running {program}`clang-tidy` on the entire affected files or the
+whole project using {program}`run-clang-tidy.py`.
 
-.. _clang-tidy-nolint:
+(clang-tidy-nolint)=
 
-Suppressing Undesired Diagnostics
-=================================
+## Suppressing Undesired Diagnostics
 
-:program:`clang-tidy` diagnostics are intended to call out code that does not
+{program}`clang-tidy` diagnostics are intended to call out code that does not
 adhere to a coding standard, or is otherwise problematic in some way. However,
 if the code is known to be correct, it may be useful to silence the warning.
 Some clang-tidy checks provide a check-specific way to silence the diagnostics,
-e.g. `bugprone-use-after-move <checks/bugprone/use-after-move.html>`_ can be
+e.g. [bugprone-use-after-move](checks/bugprone/use-after-move.md) can be
 silenced by re-initializing the variable after it has been moved out,
-`bugprone-string-integer-assignment
-<checks/bugprone/string-integer-assignment.html>`_ can be suppressed by
-explicitly casting the integer to ``char``,
-`readability-implicit-bool-conversion
-<checks/readability/implicit-bool-conversion.html>`_ can also be suppressed by
+[bugprone-string-integer-assignment](checks/bugprone/string-integer-assignment.md) can be suppressed by
+explicitly casting the integer to `char`,
+[readability-implicit-bool-conversion](checks/readability/implicit-bool-conversion.md) can also be suppressed by
 using explicit casts, etc.
 
 If a specific suppression mechanism is not available for a certain warning, or
-its use is not desired for some reason, :program:`clang-tidy` has a generic
-mechanism to suppress diagnostics using ``NOLINT``, ``NOLINTNEXTLINE``, and
-``NOLINTBEGIN`` ... ``NOLINTEND`` comments.
+its use is not desired for some reason, {program}`clang-tidy` has a generic
+mechanism to suppress diagnostics using `NOLINT`, `NOLINTNEXTLINE`, and
+`NOLINTBEGIN` ... `NOLINTEND` comments.
 
-The ``NOLINT`` comment instructs :program:`clang-tidy` to ignore warnings on
+The `NOLINT` comment instructs {program}`clang-tidy` to ignore warnings on
 the *same line* (it doesn't apply to a function, a block of code or any other
 language construct; it applies to the line of code it is on). If introducing
 the comment on the same line would change the formatting in an undesired way,
-the ``NOLINTNEXTLINE`` comment allows suppressing clang-tidy warnings on the
-*next line*. The ``NOLINTBEGIN`` and ``NOLINTEND`` comments allow suppressing
+the `NOLINTNEXTLINE` comment allows suppressing clang-tidy warnings on the
+*next line*. The `NOLINTBEGIN` and `NOLINTEND` comments allow suppressing
 clang-tidy warnings on *multiple lines* (affecting all lines between the two
 comments).
 
@@ -528,56 +512,57 @@ are ignored here, as they would effectively re-activate the warning.
 
 For example:
 
-.. code-block:: c++
-
-  class Foo {
-    // Suppress all the diagnostics for the line
-    Foo(int param); // NOLINT
+```c++
+class Foo {
+  // Suppress all the diagnostics for the line
+  Foo(int param); // NOLINT
 
-    // Consider explaining the motivation to suppress the warning
-    Foo(char param); // NOLINT: Allow implicit conversion from `char`, because <some valid reason>
+  // Consider explaining the motivation to suppress the warning
+  Foo(char param); // NOLINT: Allow implicit conversion from `char`, because <some valid reason>
 
-    // Silence only the specified checks for the line
-    Foo(double param); // NOLINT(google-explicit-constructor, google-runtime-int)
+  // Silence only the specified checks for the line
+  Foo(double param); // NOLINT(google-explicit-constructor, google-runtime-int)
 
-    // Silence all checks from the `google` module
-    Foo(bool param); // NOLINT(google*)
+  // Silence all checks from the `google` module
+  Foo(bool param); // NOLINT(google*)
 
-    // Silence all checks ending with `-avoid-c-arrays`
-    int array[10]; // NOLINT(*-avoid-c-arrays)
+  // Silence all checks ending with `-avoid-c-arrays`
+  int array[10]; // NOLINT(*-avoid-c-arrays)
 
-    // Silence only the specified diagnostics for the next line
-    // NOLINTNEXTLINE(google-explicit-constructor, google-runtime-int)
-    Foo(bool param);
+  // Silence only the specified diagnostics for the next line
+  // NOLINTNEXTLINE(google-explicit-constructor, google-runtime-int)
+  Foo(bool param);
 
-    // Silence all checks from the `google` module for the next line
-    // NOLINTNEXTLINE(google*)
-    Foo(bool param);
+  // Silence all checks from the `google` module for the next line
+  // NOLINTNEXTLINE(google*)
+  Foo(bool param);
 
-    // Silence all checks ending with `-avoid-c-arrays` for the next line
-    // NOLINTNEXTLINE(*-avoid-c-arrays)
-    int array[10];
+  // Silence all checks ending with `-avoid-c-arrays` for the next line
+  // NOLINTNEXTLINE(*-avoid-c-arrays)
+  int array[10];
 
-    // Silence only the specified checks for all lines between the BEGIN and END
-    // NOLINTBEGIN(google-explicit-constructor, google-runtime-int)
-    Foo(short param);
-    Foo(long param);
-    // NOLINTEND(google-explicit-constructor, google-runtime-int)
+  // Silence only the specified checks for all lines between the BEGIN and END
+  // NOLINTBEGIN(google-explicit-constructor, google-runtime-int)
+  Foo(short param);
+  Foo(long param);
+  // NOLINTEND(google-explicit-constructor, google-runtime-int)
 
-    // Silence all checks from the `google` module for all lines between the BEGIN and END
-    // NOLINTBEGIN(google*)
-    Foo(bool param);
-    // NOLINTEND(google*)
+  // Silence all checks from the `google` module for all lines between the BEGIN and END
+  // NOLINTBEGIN(google*)
+  Foo(bool param);
+  // NOLINTEND(google*)
 
-    // Silence all checks ending with `-avoid-c-arrays` for all lines between the BEGIN and END
-    // NOLINTBEGIN(*-avoid-c-arrays)
-    int array[10];
-    // NOLINTEND(*-avoid-c-arrays)
-  };
+  // Silence all checks ending with `-avoid-c-arrays` for all lines between the BEGIN and END
+  // NOLINTBEGIN(*-avoid-c-arrays)
+  int array[10];
+  // NOLINTEND(*-avoid-c-arrays)
+};
+```
 
-The formal syntax of ``NOLINT``, ``NOLINTNEXTLINE``, and ``NOLINTBEGIN`` ...
-``NOLINTEND`` is the following:
+The formal syntax of `NOLINT`, `NOLINTNEXTLINE`, and `NOLINTBEGIN` ...
+`NOLINTEND` is the following:
 
+```{eval-rst}
 .. parsed-literal::
 
   lint-comment:
@@ -596,21 +581,22 @@ The formal syntax of ``NOLINT``, ``NOLINTNEXTLINE``, and ``NOLINTBEGIN`` ...
     **NOLINTNEXTLINE**
     **NOLINTBEGIN**
     **NOLINTEND**
+```
 
 Note that whitespaces between
-``NOLINT``/``NOLINTNEXTLINE``/``NOLINTBEGIN``/``NOLINTEND`` and the opening
+`NOLINT`/`NOLINTNEXTLINE`/`NOLINTBEGIN`/`NOLINTEND` and the opening
 parenthesis are not allowed (in this case the comment will be treated just as
-``NOLINT``/``NOLINTNEXTLINE``/``NOLINTBEGIN``/``NOLINTEND``), whereas in the
+`NOLINT`/`NOLINTNEXTLINE`/`NOLINTBEGIN`/`NOLINTEND`), whereas in the
 check names list (inside the parentheses), whitespaces can be used and will be
 ignored.
 
-All ``NOLINTBEGIN`` comments must be paired by an equal number of ``NOLINTEND``
+All `NOLINTBEGIN` comments must be paired by an equal number of `NOLINTEND`
 comments. Moreover, a pair of comments must have matching arguments -- for
-example, ``NOLINTBEGIN(check-name)`` can be paired with
-``NOLINTEND(check-name)`` but not with ``NOLINTEND`` `(zero arguments)`.
-:program:`clang-tidy` will generate a ``clang-tidy-nolint`` error diagnostic if
-any ``NOLINTBEGIN``/``NOLINTEND`` comment violates these requirements.
-
-.. _Bear: https://github.com/rizsotto/Bear
-.. _LibTooling: https://clang.llvm.org/docs/LibTooling.html
-.. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
+example, `NOLINTBEGIN(check-name)` can be paired with
+`NOLINTEND(check-name)` but not with `NOLINTEND` `(zero arguments)`.
+{program}`clang-tidy` will generate a `clang-tidy-nolint` error diagnostic if
+any `NOLINTBEGIN`/`NOLINTEND` comment violates these requirements.
+
+[bear]: https://github.com/rizsotto/Bear
+[how to setup tooling for llvm]: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
+[libtooling]: https://clang.llvm.org/docs/LibTooling.html
diff --git a/clang-tools-extra/docs/conf.py b/clang-tools-extra/docs/conf.py
index ad1a3ae215df1..710018aa62b8f 100644
--- a/clang-tools-extra/docs/conf.py
+++ b/clang-tools-extra/docs/conf.py
@@ -24,6 +24,10 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions += ["sphinx.ext.todo", "sphinx.ext.mathjax"]
 
+# The clang-tidy documentation uses definition lists, which need the "deflist"
+# MyST extension. This matches llvm/docs/conf.py and lldb/docs/conf.py.
+myst_enable_extensions += ["deflist"]
+
 # General information about the project.
 project = "Extra Clang Tools"
 copyright = "2007-%d, The Clang Team" % date.today().year

>From dd88361a5ffee266192e03e5e5c10cf951e824b4 Mon Sep 17 00:00:00 2001
From: s4chinjha <s4chinjha at gmail.com>
Date: Fri, 13 Nov 2026 19:16:16 +0530
Subject: [PATCH 3/3] [clang-tidy][docs] address reviewer feedback

---
 .../docs/clang-tidy/Contributing.md           | 30 +++++++++----------
 .../llvmlibc/restrict-system-libc-headers.md  | 11 +++----
 clang-tools-extra/docs/conf.py                |  3 +-
 3 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.md b/clang-tools-extra/docs/clang-tidy/Contributing.md
index cee72499df420..4ad41cd9715ee 100644
--- a/clang-tools-extra/docs/clang-tidy/Contributing.md
+++ b/clang-tools-extra/docs/clang-tidy/Contributing.md
@@ -1,6 +1,6 @@
 # Getting Involved
 
-{program}`clang-tidy` has several own checks and can run Clang static analyzer
+{program}`clang-tidy` has several own checks and can run Clang Static Analyzer
 checks, but its power is in the ability to easily write custom checks.
 
 Checks are organized in modules, which can be linked into {program}`clang-tidy`
@@ -15,7 +15,7 @@ The interface provided by {program}`clang-tidy` makes it easy to write useful
 and precise checks in just a few lines of code. If you have an idea for a good
 check, the rest of this document explains how to do this.
 
-There are a few tools particularly useful when developing clang-tidy checks:
+There are a few tools particularly useful when developing Clang-Tidy checks:
 : - `add_new_check.py` is a script to automate the process of adding a new
     check; it will create the check, update the CMake file and create a test.
   - `rename_check.py` does what the script name suggests, renames an existing
@@ -72,27 +72,27 @@ may want to only enable the `X86` target in the CMake configuration.
 `llvm/clang-tools-extra` directory and is structured as follows:
 
 ```
-clang-tidy/                       # Clang-tidy core.
+clang-tidy/                       # Clang-Tidy core.
 |-- ClangTidy.h                   # Interfaces for users.
 |-- ClangTidyCheck.h              # Interfaces for checks.
-|-- ClangTidyModule.h             # Interface for clang-tidy modules.
+|-- ClangTidyModule.h             # Interface for Clang-Tidy modules.
    ...
-|-- google/                       # Google clang-tidy module.
+|-- google/                       # Google Clang-Tidy module.
 |-+
   |-- GoogleTidyModule.cpp
   |-- GoogleTidyModule.h
         ...
-|-- llvm/                         # LLVM clang-tidy module.
+|-- llvm/                         # LLVM Clang-Tidy module.
 |-+
   |-- LLVMTidyModule.cpp
   |-- LLVMTidyModule.h
         ...
-|-- objc/                         # Objective-C clang-tidy module.
+|-- objc/                         # Objective-C Clang-Tidy module.
 |-+
   |-- ObjCTidyModule.cpp
   |-- ObjCTidyModule.h
         ...
-|-- tool/                         # Sources of the clang-tidy binary.
+|-- tool/                         # Sources of the Clang-Tidy binary.
         ...
 test/clang-tidy/                  # Integration tests.
     ...
@@ -103,14 +103,14 @@ unittests/clang-tidy/             # Unit tests.
     ...
 ```
 
-## Writing a clang-tidy Check
+## Writing a Clang-Tidy Check
 
 So you have an idea of a useful check for {program}`clang-tidy`.
 
 First, if you're not familiar with LLVM development, read through the [Getting
 Started with the LLVM System][getting started with the llvm system] document for instructions on setting up your
 workflow and the [LLVM Coding Standards][llvm coding standards] document to familiarize yourself
-with the coding style used in the project. Code reviews for clang-tidy
+with the coding style used in the project. Code reviews for Clang-Tidy
 contributions are done through [LLVM Github][llvm github].
 
 Next, you need to decide which module the check belongs to. Modules
@@ -547,11 +547,11 @@ that code was not modified by fix-its, by checking that it is present
 unchanged in the fixed code. The full set of [FileCheck][filecheck] directives
 is available (e.g., `CHECK-MESSAGES-SAME:`, `CHECK-MESSAGES-NOT:`), though
 typically the basic `CHECK` forms (`CHECK-MESSAGES` and `CHECK-FIXES`)
-are sufficient for clang-tidy tests. Note that the [FileCheck][filecheck]
+are sufficient for Clang-Tidy tests. Note that the [FileCheck][filecheck]
 documentation mostly assumes the default prefix (`CHECK`), and hence
 describes the directive as `CHECK:`, `CHECK-SAME:`, `CHECK-NOT:`, etc.
 Replace `CHECK` with either `CHECK-FIXES` or `CHECK-MESSAGES` for
-clang-tidy tests.
+Clang-Tidy tests.
 
 An additional check enabled by `check_clang_tidy.py` ensures that
 if `CHECK-MESSAGES:` is used in a file then every warning or error
@@ -673,7 +673,7 @@ if you're unsure about a particular warning.
 Developing an out-of-tree check as a plugin largely follows the steps
 outlined above, including creating a new module and doing the hacks to
 register the module. The plugin is a shared library whose code lives outside
-the clang-tidy build system. Build and link this shared library against
+the Clang-Tidy build system. Build and link this shared library against
 LLVM as done for other kinds of Clang plugins. If using CMake, use the keyword
 `MODULE` while invoking `add_library` or `llvm_add_library`.
 
@@ -685,7 +685,7 @@ $ clang-tidy --checks=-*,my-explicit-constructor -list-checks -load myplugin.so
 ```
 
 There are no expectations regarding ABI and API stability, so the plugin must
-be compiled against the version of clang-tidy that will be loading the plugin.
+be compiled against the version of Clang-Tidy that will be loading the plugin.
 
 The plugins can use threads, TLS, or any other facilities available to in-tree
 code which is accessible from the external headers.
@@ -698,7 +698,7 @@ Alternatively, get [lit][lit] following the [test-suite guide][test-suite guide]
 [FileCheck][filecheck] binary, and write a version of [check_clang_tidy.py][check_clang_tidy.py] to suit your
 needs.
 
-## Running clang-tidy on LLVM
+## Running Clang-Tidy on LLVM
 
 To test a check, it's best to try it out on a larger code base. LLVM and Clang
 are the natural targets as you already have the source code around. The most
diff --git a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
index 9336598f5f83f..943238851295f 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md
@@ -20,14 +20,15 @@ because they are ABI incompatible.
 
 ## Options
 
-:::{option} Includes
+```{option} Includes
 A string containing a comma separated glob list of allowed include
-filenames. Similar to the -checks glob list for running clang-tidy itself,
-the two wildcard characters are `*` and `-`, to include and exclude globs,
-respectively. The default is `-*`, which disallows all includes.
+filenames. Similar to the `-checks` glob list for running
+{program}`clang-tidy` itself, the two wildcard characters are `*` and `-`,
+to include and exclude globs, respectively. The default is `-*`, which
+disallows all includes.
 
 This can be used to allow known safe includes such as Linux development
 headers. See {doc}`portability-restrict-system-includes
 <../portability/restrict-system-includes>` for more
 details.
-:::
+```
diff --git a/clang-tools-extra/docs/conf.py b/clang-tools-extra/docs/conf.py
index 710018aa62b8f..f7635539aaa65 100644
--- a/clang-tools-extra/docs/conf.py
+++ b/clang-tools-extra/docs/conf.py
@@ -24,8 +24,7 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions += ["sphinx.ext.todo", "sphinx.ext.mathjax"]
 
-# The clang-tidy documentation uses definition lists, which need the "deflist"
-# MyST extension. This matches llvm/docs/conf.py and lldb/docs/conf.py.
+# MyST extension.
 myst_enable_extensions += ["deflist"]
 
 # General information about the project.



More information about the cfe-commits mailing list