[clang-tidy] Organize test docs into subdirectories by module (NFC)

[LegalizeAdulthood]

Summary

• Rename doc files
• Update add_new_check.py to handle doc subdirs
• Improve add_new_check.py to preserve static analyzer doc anchors

[LegalizeAdulthood]

• Update add_new_check.py for the case when adding a new check, not just updating the docs
• Rebase ReleaseNotes.rst

[LegalizeAdulthood]

I know this is a rather huge diff, but the part that needs to be reviewed is the python script changes.

I've rebuilt the HTML docs with sphinx and tested all the manually modified links to verify that they still go to the correct page.

The existing Release Notes have been rebased as well.

[njames93]

Can I ask what the motivation is for this change?

You may want to check the actual header files for the checks. A lot of them have a comment saying.

/// For the user-facing documentation see:
/// http://clang.llvm.org/extra/clang-tidy/checks/bugprone-reserved-identifier.html

I'm no expert on the inner workings of search engines, but I feel this will temporarily mess up my go to way of finding out a checks documentation, just googling its name.
I wouldn't say its reason for blocking this, just my 0.02$.

clang-tools-extra/clang-tidy/add_new_check.py

86–87

Again, this comment would need to be updated to use the new directory structure/

[LegalizeAdulthood]

In D126495#3552887, @njames93 wrote:

Can I ask what the motivation is for this change?

https://discourse.llvm.org/t/clang-tidy-rfc-use-module-name-as-a-directory-for-organizing-files/62499

[LegalizeAdulthood]

In D126495#3553183, @LegalizeAdulthood wrote:

In D126495#3552887, @njames93 wrote:

Can I ask what the motivation is for this change?

https://discourse.llvm.org/t/clang-tidy-rfc-use-module-name-as-a-directory-for-organizing-files/62499

Basically there are a crapton of files in a single directory, making for clutter.

Additionally, on Windows, TAB completion of filenames in cmd shells doesn't stop at the first non-unique character in a path, so it's essentially useless when a crapton of files all begin with the same prefix. If the files are grouped by module, then I can TAB complete on the module and usually the checks differ after a few characters in the check name once the module prefix is stripped, so typing a few characters and then TAB completes to the desired file or a few more TABs to cycle through the remaining matching files to get the one I want.

[LegalizeAdulthood]

Gentle ping

[njames93]

In D126495#3568998, @LegalizeAdulthood wrote:

Gentle ping

My previous point about the links in the header files not being updated hasn't been addressed.

It would also be nice if there was a redirect that would dynamically translate the old links to new links. A regex like this would do the job, but I have no idea on the inner workings of sphinx in order to set this up: -clang-tidy/checks/(\w+)((-\w+)+) -> clang-tidy/checks/$1/$2

[LegalizeAdulthood]

In D126495#3569029, @njames93 wrote:

In D126495#3568998, @LegalizeAdulthood wrote:

Gentle ping

My previous point about the links in the header files not being updated hasn't been addressed.

Ah yes, I got distracted and forgot about that. I will update the diff.

It would also be nice if there was a redirect that would dynamically translate the old links to new links.

You can do that with .htaccess, but I don't know if that's considered acceptable in clang documentation.

Leaving .rst pages in place for all the old locations just recreates the clutter instead of getting rid of it.

[LegalizeAdulthood]

• Update add_new_check.py to write out module subdir link in generated header
• Update all links in check headers

[aaron.ballman]

In D126495#3569863, @LegalizeAdulthood wrote:

In D126495#3569029, @njames93 wrote:

It would also be nice if there was a redirect that would dynamically translate the old links to new links.

You can do that with .htaccess, but I don't know if that's considered acceptable in clang documentation.

FWIW, I don't have any idea if this is or isn't acceptable.

Leaving .rst pages in place for all the old locations just recreates the clutter instead of getting rid of it.

+1

I don't feel super comfortable reviewing the Python changes, but I spot checked the changes and they all seem reasonable to me. So this has my LG, but I'm not accepting the review because of the Python bit.

[LegalizeAdulthood]

In D126495#3570767, @aaron.ballman wrote:

In D126495#3569863, @LegalizeAdulthood wrote:

In D126495#3569029, @njames93 wrote:

It would also be nice if there was a redirect that would dynamically translate the old links to new links.

You can do that with .htaccess, but I don't know if that's considered acceptable in clang documentation.

FWIW, I don't have any idea if this is or isn't acceptable.

Mucking around with an .htaccess file is very web server dependent. Surely this can't be the first time that a page of documentation changed names or locations? I'm betting that they didn't worry about putting in redirects and let search engines handle guiding users to the correct page.

[njames93]

In D126495#3571403, @LegalizeAdulthood wrote:

In D126495#3570767, @aaron.ballman wrote:

In D126495#3569863, @LegalizeAdulthood wrote:

In D126495#3569029, @njames93 wrote:

It would also be nice if there was a redirect that would dynamically translate the old links to new links.

You can do that with .htaccess, but I don't know if that's considered acceptable in clang documentation.

FWIW, I don't have any idea if this is or isn't acceptable.

Mucking around with an .htaccess file is very web server dependent. Surely this can't be the first time that a page of documentation changed names or locations? I'm betting that they didn't worry about putting in redirects and let search engines handle guiding users to the correct page.

Search engines isn't really an issue, its more people who are using older versions of llvm that try and go to the documentation which turns out is a dead link.
Having said that, I still think the lack of a redirect shouldn't block this change.

[LegalizeAdulthood]

In D126495#3571511, @njames93 wrote:

Search engines isn't really an issue, its more people who are using older versions of llvm that try and go to the documentation which turns out is a dead link.
Having said that, I still think the lack of a redirect shouldn't block this change.

Aren't we archiving old versions of the documentation, though?

So if I know I'm using LLVM 3.8, I would consult the documentation for 3.8 not top-of-tree, and all the links would work correctly within the 3.8 documentation, adjusting for the base path.

[LegalizeAdulthood]

Ping. All review comments should be addressed in the latest diff.

[aaron.ballman]

In D126495#3574115, @LegalizeAdulthood wrote:

In D126495#3571511, @njames93 wrote:

Search engines isn't really an issue, its more people who are using older versions of llvm that try and go to the documentation which turns out is a dead link.
Having said that, I still think the lack of a redirect shouldn't block this change.

Aren't we archiving old versions of the documentation, though?

We do:

https://releases.llvm.org/12.0.0/tools/clang/tools/extra/docs/
https://releases.llvm.org/11.0.0/tools/clang/tools/extra/docs/
and so on.

Giving my LG more officially now to unblock this, but I'd still appreciate some extra eyes on the Python changes.

[LegalizeAdulthood]

In D126495#3588787, @aaron.ballman wrote:

In D126495#3574115, @LegalizeAdulthood wrote:

In D126495#3571511, @njames93 wrote:

Search engines isn't really an issue, its more people who are using older versions of llvm that try and go to the documentation which turns out is a dead link.
Having said that, I still think the lack of a redirect shouldn't block this change.

Aren't we archiving old versions of the documentation, though?

We do:

https://releases.llvm.org/12.0.0/tools/clang/tools/extra/docs/
https://releases.llvm.org/11.0.0/tools/clang/tools/extra/docs/
and so on.

Giving my LG more officially now to unblock this, but I'd still appreciate some extra eyes on the Python changes.

I tested by generating a new check and validating the links in the documentation as well as running --update-docs and checking that the updates were correct. So functionally, there should be no problem and I tried to follow the existing style of the file, so should be good on style nits as well.