<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Apr 15, 2014 at 6:38 PM, Reid Kleckner <span dir="ltr"><<a href="mailto:rnk@google.com" target="_blank">rnk@google.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div class="">On Tue, Apr 15, 2014 at 3:25 PM, Sean Silva <span dir="ltr"><<a href="mailto:chisophugis@gmail.com" target="_blank">chisophugis@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">Thanks for the patch. I love the direction but I think it can be simplified quite a bit using the following information:<div>
<br></div><div>Note that Makefile.sphinx is just a "boilerplate" file generated by "sphinx-quickstart" and not integrated in any way with LLVM's build system. We don't need all the functionality in Makefile.sphinx; in fact, we really only need the default (`html`) (and clean obviously; and maybe `man` once we rig up the install of the manpages).</div>
</div></blockquote><div><br></div></div><div>I agree. This is more complicated than necessary. I'd love it if we had a 'docs' target that generated html output identical to what we publish on the web in ${build}/docs. We don't need any other targets other than clang-docs and maybe lld-docs.</div>
</div></div></div></blockquote><div><br></div><div>It's not integrated with the build, but `cd docs/; make -f Makefile.sphinx; $BROWSER _build/html/foo.html` will do that if you need it now. See docs/README.txt for more information.</div>
<div><br></div><div>Personally I don't mind have the docs build decoupled from the regular build; it's convenient in some respects. However, I definitely see the appeal of having it integrated into the regular build as well and am all for it (for one, it would get a bit more attention paid to the docs as it would seamlessly fit in with the usual workflow).<br>
</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div class="">
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div>I don't think it is a good idea to add "linkcheck" as part of the build for two reasons:</div>
<div>1. we don't want the build to require an internet connection</div><div>2. we don't want to allow the content of an external website (which may change arbitrarily) to break the build.</div>
<div>Also, it's just not an actionable thing for your average developer.</div></div><div><br></div><div>Let's see what the patch looks like taking that into account.</div><div><br></div><div>Btw, Thanks for tackling issues at the intersection of the docs and the build system. Very brave. If you understand how the CMake install works, it would be a godsend to have it install the manpages (generated by Sphinx's `-b man`) as part of the usual install (if the docs were built, of course).</div>
</div></blockquote><div><br></div></div><div>I don't think our current docs are useful as man pages. We'd want to make stripped down docs for each of the tools (llc, opt, clang), and try to document all the options. Nobody needs 'man llvmLangRef' or 'man llvmInAlloca'.</div>
</div></div></div></blockquote><div><br></div><div>I mean the stuff in docs/CommandGuide/, which are specifically man pages (see docs/README.txt). Those are the only ones that get built by the man target (see conf.py:215).</div>
<div><br></div><div>-- Sean Silva </div></div><br></div></div>