Page MenuHomePhabricator

[docs] Regenerate DiagnosticsReference.rst
ClosedPublic

Authored by rsandifo-arm on May 1 2020, 8:49 AM.

Details

Summary

It looks like it has been a while since the checked-in version of
DiagnosticsReference.rst was regenerated. I realise there probably
isn't any expectation that the checked-in version is kept up-to-date,
but now that the project is on github and the rst can be viewed directly
from the repo's web interface, it seemed worth having something a bit
more recent.

Diff Detail

Event Timeline

rsandifo-arm created this revision.May 1 2020, 8:49 AM
Herald added a project: Restricted Project. · View Herald Transcript

There's no good reason for this file to exist; documenting the warning options is useful, but the file should be generated as an intermediate output of the documentation build and then ultimately fed into Sphinx.

There's even a TODO in the docs about it:

TODO: Generate this from tblgen. Define one anchor per warning group.

rsandifo-arm abandoned this revision.Mon, May 4, 11:12 AM

OK, I'll leave the file as-is in that case.

OK, I'll leave the file as-is in that case.

I think it's preferable to commit the file in its updated state so that the public documentation is kept up to date rather than being left stale. However, we should also work to move this file to be built on demand like the attribute reference already is.

rsmith added a subscriber: rsmith.Mon, May 4, 1:14 PM

There's no good reason for this file to exist; documenting the warning options is useful, but the file should be generated as an intermediate output of the documentation build and then ultimately fed into Sphinx.

There's even a TODO in the docs about it:

TODO: Generate this from tblgen. Define one anchor per warning group.

We do generate this document with tblgen already. The problem is that it's not automatically regenerated as part of the docs build on the website, unlike some of our other similar tblgen-generated documentation. I've asked for that to happen repeatedly for years but so far I have achieved zero traction. So the best we have right now is to manually regenerate this every once in a while and check it in. :-(

There's no good reason for this file to exist; documenting the warning options is useful, but the file should be generated as an intermediate output of the documentation build and then ultimately fed into Sphinx.

There's even a TODO in the docs about it:

TODO: Generate this from tblgen. Define one anchor per warning group.

We do generate this document with tblgen already. The problem is that it's not automatically regenerated as part of the docs build on the website, unlike some of our other similar tblgen-generated documentation. I've asked for that to happen repeatedly for years but so far I have achieved zero traction. So the best we have right now is to manually regenerate this every once in a while and check it in. :-(

Do we need support from the website ops people on this, or do we just need to set up the build system properly to do it?

rsmith added a comment.Mon, May 4, 2:51 PM

We do generate this document with tblgen already. The problem is that it's not automatically regenerated as part of the docs build on the website, unlike some of our other similar tblgen-generated documentation. I've asked for that to happen repeatedly for years but so far I have achieved zero traction. So the best we have right now is to manually regenerate this every once in a while and check it in. :-(

Do we need support from the website ops people on this, or do we just need to set up the build system properly to do it?

My understanding is that there's a custom script on the website that runs some clang-tblgen invocations as part of the docs build process, and it's not something that we can modify by changing anything that's checked into git. (I mean, we could hack around it by detecting one of the tablegen invocations that's already performed and doing more work on the side, but that's clearly the wrong way to get this to work...)

We do generate this document with tblgen already. The problem is that it's not automatically regenerated as part of the docs build on the website, unlike some of our other similar tblgen-generated documentation. I've asked for that to happen repeatedly for years but so far I have achieved zero traction. So the best we have right now is to manually regenerate this every once in a while and check it in. :-(

Do we need support from the website ops people on this, or do we just need to set up the build system properly to do it?

My understanding is that there's a custom script on the website that runs some clang-tblgen invocations as part of the docs build process, and it's not something that we can modify by changing anything that's checked into git. (I mean, we could hack around it by detecting one of the tablegen invocations that's already performed and doing more work on the side, but that's clearly the wrong way to get this to work...)

Okay. So it doesn't just run ninja docs-clang-html? That's unfortunate.

rsmith added a comment.Mon, May 4, 5:19 PM

Okay. So it doesn't just run ninja docs-clang-html? That's unfortunate.

It didn't last time I looked into this. And http://clang.llvm.org/docs/DiagnosticsReference.html shows the "before" state of this patch, not the "after", so I think it still doesn't.

Okay. So it doesn't just run ninja docs-clang-html? That's unfortunate.

It didn't last time I looked into this. And http://clang.llvm.org/docs/DiagnosticsReference.html shows the "before" state of this patch, not the "after", so I think it still doesn't.

Okay. And I can verify that it is in fact rebuilt by docs-clang-html. So I agree that we should continue taking patches like this in the short term, and maybe we can restart that conversation about the website. It's hard to imagine why we would be able to run clang-tblgen as part of the server build but not a full docs-clang-html build. It's not like clang-tblgen wouldn't still need to be sandboxed.

rsandifo-arm reclaimed this revision.Tue, May 5, 10:41 AM

OK, thanks! Reclaiming and reopening the revision in that case.

This revision was not accepted when it landed; it landed in state Needs Review.Wed, May 6, 2:39 AM
This revision was automatically updated to reflect the committed changes.