On Mon, Jun 22, 2015 at 5:27 PM, Sean Silva <chisophu...@gmail.com> wrote: > > > On Mon, Jun 22, 2015 at 11:18 AM, Aaron Ballman <aa...@aaronballman.com> > wrote: >> >> On Mon, Jun 22, 2015 at 1:59 PM, Douglas Gregor <dgre...@apple.com> wrote: >> > >> >> On Jun 22, 2015, at 10:31 AM, Aaron Ballman <aa...@aaronballman.com> >> >> wrote: >> >> >> >> On Mon, Jun 22, 2015 at 1:06 PM, Douglas Gregor <dgre...@apple.com> >> >> wrote: >> >>> Author: dgregor >> >>> Date: Mon Jun 22 12:06:56 2015 >> >>> New Revision: 240296 >> >>> >> >>> URL: http://llvm.org/viewvc/llvm-project?rev=240296&view=rev >> >>> Log: >> >>> Document the nullability attributes. >> >> >> >> Thank you! >> >> >> >>> >> >>> Modified: >> >>> cfe/trunk/docs/AttributeReference.rst >> >>> cfe/trunk/include/clang/Basic/Attr.td >> >>> cfe/trunk/include/clang/Basic/AttrDocs.td >> >>> >> >>> Modified: cfe/trunk/docs/AttributeReference.rst >> >> >> >> Please do not commit changes to AttributeReference.rst directly. This >> >> file is automatically generated on the server (daily) from >> >> AttrDocs.td. It exists because we need it for folks who want to >> >> generate documentation locally. >> >> >> >> I think it's time to change the contents of this file to be nothing >> >> but a comment saying, "Please do not commit changes to this file", but >> >> the downside is that will kill off AttributeReference.html on the live >> >> site until the server generates the new documentation. I am starting >> >> to suspect that pain may be worth it, and I might do this task later >> >> tonight. >> > >> > Neither of these workflows are intuitive for the developer. >> >> Strongly agreed. >> >> > Why aren’t we building AttributeReference.rst into the build directory >> > as part of the documentation build, as one would expect? >> >> It wasn't that this wasn't desirable, it was because it was hard >> (especially for the server side of things, IIRC). > > > It is useful to keep the documentation build independent from the "code" > build. Assuming clang-tblgen to always be present would lose this property.
Good point. >> Going from memory (this was discussed on the lists when we did this >> work initially though): that turned out to be prohibitively difficult >> to accomplish. clang-tblgen lives in the build folder, but the >> documentation does not (it lives in the source folder which we don't >> usually want to write changes back into), and the build folder for the >> documentation is not the same as the build folder for where >> clang-tblgen lives. > > > It should be when the documentation is being built through the CMake build. I don't think the server-side process that generates the attribute documentation currently uses CMake, but Tanya would be able to speak to that better than I. >> I think the ultimate idea was that we'd need to >> write a Sphinx plugin to make this work, and now people have more >> dependency issues (and that still needs to solve the "where does >> clang-tblgen live" problem). > > > A Sphinx plugin would allow us to switch over to "TableGen-like" structure > inside rst file (vs. our current rst inside TableGen). This would avoid the > need for clang-tblgen to be present when building the docs, but would > require sphinx to be around when building the code. I'm not sure which is > preferable, but the current scheme doesn't seem much better/worse. Ah, thank you for the information Sean. I knew someone would recall this better than I. The build system parts of this are definitely not my area of expertise. :-) Is there a desire to get rid of the server-side build process and instead replace it with one where the developer is required to update AttrDocs.td, generate the documentation with clang-tblgen (likely through an automated build target) to get the RST file, and then commit AttrDocs.td and AttributeReference.rst when they make a modification to the attribute documentation? ~Aaron > > -- Sean Silva > >> >> >> > Having to manually call clang-tblgen to update AttributeReference.rst, >> > then separately build the docs with Sphinx, then avoid committing the >> > changes… makes improving documentation harder than it should be. >> >> The thought was that you didn't need to run clang-tblgen and build the >> docs manually in the first place (because RST is supposed to be >> trivial). That being said, I like the idea of making things testable >> locally and would prefer if we could do that. If you (or anyone) has >> ideas on how to improve this, patches are very much welcome. >> >> ~Aaron >> >> > >> > - Doug >> > >> >> _______________________________________________ >> cfe-commits mailing list >> cfe-commits@cs.uiuc.edu >> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits > > _______________________________________________ cfe-commits mailing list cfe-commits@cs.uiuc.edu http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
