llvm dev - Apr 2017 - Debugging Docs and llvm.org/docs/

> On 3 Apr 2017, at 22:47, Alex Denisov <1101.debian at gmail.com>
wrote:
> 
> The HTML generated using sphinx[1].
> At the bottom of each page you can see actual version of sphinx used to
generate this page.
> 
Thanks -- interesting that the docs haven't been updated since March 15th:

© Copyright 2003-2017, LLVM Project. Last updated on 2017-03-16. Created using
Sphinx 1.4.5.
>> - How should I best debug whether the docs (in RST) are syntactically
correct? Are there recommended practices for doing a sanity check on the docs?
> 
> Just run correct version of sphinx locally and check whether everything is
correct.
> 
I see -- nothing part of the CMake build, say "check-docs" that would
do this?
>> - How often do the documents get built and uploaded to the website?
> 
> AFAIK it happens once per hour (cron-task with polling).
> 
Cool -- is this cron job running on the llvm.org <http://llvm.org/> server
itself, or somewhere else?
> CC’ing Renato in case I missed something.
> 
Thanks, Alex!
>> On 3. Apr 2017, at 14:33, Dean Michael Berris via llvm-dev <llvm-dev
at lists.llvm.org> wrote:
>> 
>> Hi -- I've recently added some documentation to the LLVM docs
subdirectory, and was wondering about a couple of things:
>> 
>> - How should I best debug whether the docs (in RST) are syntactically
correct? Are there recommended practices for doing a sanity check on the docs?
>> - How often do the documents get built and uploaded to the website?
>> 
>> Cheers
>> 
>> -- Dean
>> 
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
> 
> [1] http://www.sphinx-doc.org/en/stable/
> 
> -- 
> AlexDenisov
> Software Engineer, https://lowlevelbits.org
> 
-- Dean

-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20170403/de2ce2c3/attachment.html>

On Mon, Apr 3, 2017 at 5:51 AM, Dean Michael Berris via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
>
> On 3 Apr 2017, at 22:47, Alex Denisov <1101.debian at gmail.com>
wrote:
>
> The HTML generated using sphinx[1].
> At the bottom of each page you can see actual version of sphinx used to
> generate this page.
>
>
> Thanks -- interesting that the docs haven't been updated since March
15th:
>
> © Copyright 2003-2017, LLVM Project. Last updated on 2017-03-16. Created
> using Sphinx 1.4.5.
>
> - How should I best debug whether the docs (in RST) are syntactically
> correct? Are there recommended practices for doing a sanity check on the
> docs?
>
>
> Just run correct version of sphinx locally and check whether everything is
> correct.
>
>
> I see -- nothing part of the CMake build, say "check-docs" that
would do
> this?
>
>
LLVM_ENABLE_SPHINX will turn it on.
 //Use Sphinx to generate llvm documentation.
 LLVM_ENABLE_SPHINX:BOOL=OFF
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20170403/0a61b9ee/attachment.html>

On 3 April 2017 at 13:51, Dean Michael Berris <dean.berris at gmail.com>
wrote:
> Thanks -- interesting that the docs haven't been updated since March
15th:
Yes, this happens when the server's sphinx installation picked up on
something that neither your installation or the buildbot's did.

I'll have a look if I can untangle that.

cheers,
--renato

PS: We really need a better way of doing this...

On 3 April 2017 at 13:59, Daniel Berlin via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
> LLVM_ENABLE_SPHINX will turn it on.
>  //Use Sphinx to generate llvm documentation.
>  LLVM_ENABLE_SPHINX:BOOL=OFF
FYI, what the polling server does is:

$ cmake -DLLVM_ENABLE_DOXYGEN=ON -DLLVM_BUILD_DOCS=ON
-DCLANG_TOOLS_EXTRA_INCLUDE_DOCS=ON $SRC_DIR
$ make doxygen

This builds llvm, clang clang-extra and polly (if checked out) docs.
I'm not sure why the extra needs its own flag, though.

cheers,
--renato

On 3 April 2017 at 13:59, Daniel Berlin via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
>
>
> On Mon, Apr 3, 2017 at 5:51 AM, Dean Michael Berris via llvm-dev
> <llvm-dev at lists.llvm.org> wrote:
>>
>>
>> On 3 Apr 2017, at 22:47, Alex Denisov <1101.debian at gmail.com>
wrote:
>>
>> The HTML generated using sphinx[1].
>> At the bottom of each page you can see actual version of sphinx used to
>> generate this page.
>>
>>
>> Thanks -- interesting that the docs haven't been updated since
March 15th:
>>
>> © Copyright 2003-2017, LLVM Project. Last updated on 2017-03-16.
Created
>> using Sphinx 1.4.5.
>>
>> - How should I best debug whether the docs (in RST) are syntactically
>> correct? Are there recommended practices for doing a sanity check on
the
>> docs?
>>
>>
>> Just run correct version of sphinx locally and check whether everything
is
>> correct.
>>
>>
>> I see -- nothing part of the CMake build, say "check-docs"
that would do
>> this?
>>
>
> LLVM_ENABLE_SPHINX will turn it on.
>  //Use Sphinx to generate llvm documentation.
>  LLVM_ENABLE_SPHINX:BOOL=OFF
Just to add to that the targets you want are

docs-llvm-html
docs-llvm-man

e.g.

```
ninja docs-llvm-html
```

as Daniel mentioned you need to set `LLVM_ENABLE_SPHINX` to on.

Related question:

Why do we have both a) http://llvm.org/doxygen/ and b) 
http://llvm.org/docs/doxygen/?

Google only seems to index b), but it's not been re-generated since 
January 2016. Can it be deleted?

Is there a robots.txt or similar that's preventing search engines from 
crawling a)?

Tobias


On 04/03/2017 08:03 AM, Renato Golin via llvm-dev wrote:
> On 3 April 2017 at 13:51, Dean Michael Berris <dean.berris at
gmail.com> wrote:
>> Thanks -- interesting that the docs haven't been updated since
March 15th:
> Yes, this happens when the server's sphinx installation picked up on
> something that neither your installation or the buildbot's did.
>
> I'll have a look if I can untangle that.
>
> cheers,
> --renato
>
> PS: We really need a better way of doing this...
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
-- 
Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum,
a Linux Foundation Collaborative Project.

> On 3 Apr 2017, at 23:03, Renato Golin <renato.golin at linaro.org>
wrote:
> 
> On 3 April 2017 at 13:51, Dean Michael Berris <dean.berris at
gmail.com> wrote:
>> Thanks -- interesting that the docs haven't been updated since
March 15th:
> 
> Yes, this happens when the server's sphinx installation picked up on
> something that neither your installation or the buildbot's did.
> 
> I'll have a look if I can untangle that.
> 
Thanks Renato!
> cheers,
> --renato
> 
> PS: We really need a better way of doing this...

Has anybody looked into potentially getting the LLVM docs hosted on
readthedocs.org <http://readthedocs.org/> and automatically built from the
LLVM Git mirror (or through Subversion post-commit hooks)? Since we're
already using Sphinx, this seems like a low-cost, low-interference way of
hosting the generated documentation.

-- Dean

-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20170406/c4440bdf/attachment.html>