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