On Mon, Jun 22, 2015 at 3:44 PM, Aaron Ballman <aa...@aaronballman.com> wrote:
> 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? > That is what we do for clang-format options IIRC (through some scripts in clang/docs/tools). It seems to effectively decouple the source build from the docs build, while requiring somebody to regenerate the rst from time to time (if a developer has forgotten to update it when changing the "source" that generates the rst). Actually, what would be almost ideal is a bot that watches changes to the TableGen files, and commits an upated rst file automatically. But that's a bit beyond my expectations for our current infrastructure. -- Sean Silva > > ~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
