<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=https://github.com/llvm/llvm-project/issues/65725>65725</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            Linting Clang documentation
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
            infrastructure,
            clang,
            new issue
      </td>
    </tr>

    <tr>
      <th>Assignees</th>
      <td>
      </td>
    </tr>

    <tr>
      <th>Reporter</th>
      <td>
          cor3ntin
      </td>
    </tr>
</table>

<pre>
    It would be nice to be able to catch and report during Pre Commit checks syntax errors in the RsT as these are frequents and easy to miss.

Some Clang RsT files are created by TableGen, so that leaves us with 2 options:

## Only checking the non-generated documentation files.
This is fairly easy, we can run an existing action to run `sphinx-build` in `clang/docs`, and there are pre-existing actions that could
be adapted to make this work, at least once #65664 is fixed. 

Unfortunately, for that we would have to ignore all references / missing files errors as some of the generated files would not exist.

## Build the docs as part of the existing CI checks

The idea would be to run both `check-clang` and `docs-clang-html` in the same job.
This would be enough to fail CI on invalid docs, which is not bad.
To report errors, we can:
  - Force sphinx to log the errors in a file in addition of the output using the env variable `SPHINXOPTS`
  - Add an action after the build that parse that logs and turn it into annotations. I started to looking into the viability of that
 https://github.com/cor3ntin/llvm-sphinx-log-collector/blob/main/src/index.ts - it seems doable
    Linting would appear as a check in github's PR interface
 - This would require installing sphinx and requirements on the build agent.

The issue with that approach is that it's more work, and each project would have to adapt slightly.
But talking to @AaronBallman we are eventually going to make sure we don't ignore generated files, so we might as well start now.
LLDB also has different requirements.

Not sure when I'll have time to do more thinkering there (if you are interesting on taking on that work let me know!), but i wanted to write up what I found.

Reporting formatting, compilation and clang-tidy errors in the same way would be neat too.
</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJyUVkuP6jwS_TVmUwIFAwksWPRDzLR09d3WvT3SbCtJhfi2YzN2BZp_Pyo79Eujkb5Nt0niepxz6tgYozk6or3a3KvN4wxH7n3YNz6sHBs3q3173T8xXPxoW6gJnGkI2MsSa5uWDXLTA7oWAp18YGjHYNwRngPBgx8Gw9D01LxGiFfH-AYUgg8RjAPuCX7FF8Aoy0iAgaAL9J-RHMcUkzBeJctgYlyo4lEVd9NfvVSbezPgkdTmUeltz3yKanWn9EHpw9FwP9aLxg9KH6w93_7NT8H_oYaVPmCMxFHpw3Jd7IrlTulDhXVXrZtqvloul_N1qbfz3Yr0vCDd6m1Zb9fbUuldruC3HwgeLLpjaqIzlmLqoAmETC3UV3gRlP5BTukHiB64RwZLeKYIY4SL4R40-BMb71LtXxpcKb2Cn85eM4ACqiDmvJsfyVFISVrfjAM5RomRi5hweulNBBOhQxPsNSEpZVwIGnQQRgfogN5MZImMTQrAPr1RZRFPvXFv83o0tlVlIXypsmikX6UPrW-iKgsJKDRxTyHTdwo0_xY05r4bEVEuTeTT4knqF27xlYCl2osPrylkQikyeNcQKL0qN2W5Ts2YN2oX8Bmof7nOBx4dMtnUYedDznihSbk9npNWzdF5qdNaCNRRINdQBKUPSV9ScWZxkihGiEKy7xLwH6Dnr3Js5zmjuPgf7N0LemmzACYBTxj4FvAdp4enaUY-h3jpCUxL-DF9Ezm15z5xIVvmmZGySDyospBE-eG858FO1Em6iAPBH19_1sd7bHJ-PPaSokNjpSLvwLgzWpNEFpN2etP0QoM0XWN7i-Rvs5-B-5DZu6YB5nDwoSHIupJE1mdBfxgCJmTTqm1NEuQElR_5NDKM8TYF5M5wxmCSDamy-P38z6e__v3z-eW3yPI9513biswndWPHFNL2eiIGWRiJNI2mP2bb4TE4MAzGsQd0zuf5igt4gsgYJuVa79NYps8k7Nlgbazha64beark_5jTzWxvBjXNnfXHeeOtpYZ9UPpQW18rfRgwfRlDo_TBuJbeFhxhLrVGoiFC6wWRGwAAP4xLEstE4-lEGESHmBUnWOdylK4iPP-SXih02NxizOGTUMSbTRCGIqO1EnjiMx8A6e2Q3Nu7T0DjkdzXAUnqjnGk7IIJfjydgsessPTAcKpqkKF994Z0KjQ9TE7-bcSTr0C05tizvU4p70cGRpst1INaF3cYvLtHawd0olWxLjqT4xGtvcLRT58mb4qj5JcZdkpXfLORb34wefyFYJDkAvKFrM16AecvUzE_fjzeA9rooccIremSEfEX9L5A9ZfnqYSeHDwpXVk79WuG1HTrM0bcG_dKYZqRINa5NR1c_ZgaTNRSthyhB19vq-SWPryCJYaB4NX5i5yweidd1SODgQu6SfaXYJhgPMFF9j1B50fXfin5V7KDZKg-DMiylEiNH07G5rNKiMw-xaa9frsWJK-64PXT1YOQgb1fzNr9qt2tdjij_bLcrZelXlXVrN-3VbtZ4VrX3bbdIGJVVHW73q0q3WKHWs_MXhd6VeyKbbFd7VbVQle7XUlNU6yxIip2al3QgMYuZBIXPhxnSaL7clPpzcxiTTamu5LWxnUBI4ex4TGQ0lrpB6X1dD5OvxxdssjlyeZxFvZpxOvxGNW6sCZy_EjFhi3tb_OaLxZfTvfZGOz-b19zUn655qQm_hsAAP__glNYRg">