llvm dev - Aug 2015 - [LLVMdev] [libcxx] How to update libcxx.llvm.org to use Sphinx generated doc?

Hi All,

I'm working on rewriting libc++'s documentation using Sphinx.
Hopefully it will be easier to write and maintain documentation using
restructured text and not HTML.

What steps do I need to take to get libc++ a Sphinx builder and get
the required changes made for libcxx.llvm.org?

/Eric

CC Tanya and ping.

On Mon, Jul 20, 2015 at 1:41 PM, Eric Fiselier <eric at efcs.ca>
wrote:
> Hi All,
>
> I'm working on rewriting libc++'s documentation using Sphinx.
> Hopefully it will be easier to write and maintain documentation using
> restructured text and not HTML.
>
> What steps do I need to take to get libc++ a Sphinx builder and get
> the required changes made for libcxx.llvm.org?
>
> /Eric

Eric,

I believe I can help you with this. There is a script on llvm.org that generates
the sphinx docs for the web and it would need to be modified to build your
documentation as well.

Please structure it like clang to make it easier on my side. So have a docs
directory and contain all sphinx docs there. Then the command to generate should
be 'make html' or 'make -f Makefile.sphinx html'. I think the
generated docs go in _build/html

If its ready to go, then I could try to add it, but my bandwidth is limited for
the next week due to mailing list moves so I wont have a lot of time to
troubleshoot.

Thanks,
Tanya


> On Jul 28, 2015, at 12:29 PM, Eric Fiselier <eric at efcs.ca> wrote:
> 
> CC Tanya and ping.
> 
> On Mon, Jul 20, 2015 at 1:41 PM, Eric Fiselier <eric at efcs.ca>
wrote:
>> Hi All,
>> 
>> I'm working on rewriting libc++'s documentation using Sphinx.
>> Hopefully it will be easier to write and maintain documentation using
>> restructured text and not HTML.
>> 
>> What steps do I need to take to get libc++ a Sphinx builder and get
>> the required changes made for libcxx.llvm.org?
>> 
>> /Eric

Hi Eric,

On 20 July 2015 at 10:41, Eric Fiselier <eric at efcs.ca>
wrote:
> Hi All,
>
> I'm working on rewriting libc++'s documentation using Sphinx.
> Hopefully it will be easier to write and maintain documentation using
> restructured text and not HTML.
>
> What steps do I need to take to get libc++ a Sphinx builder and get
> the required changes made for libcxx.llvm.org?
To add a documentation builder for the buildbot infrastructure here
are the basic steps.

0. Check with Dmitri Gribenko (CC'ed) that he is happy to host another
builder for the libcxx documentation on his build slave. If not you
will have to find another buildbot slave to use when you add an entry
to ``_get_documentation_builders()`` in step 3.

1. Add support for building the docs in the CMake build for libcxx.
Use the ``add_sphinx_target()`` function [1]. This is necessary
because the buildbot relies on the CMake generated targets for
building the documentation.

2. Teach getSphinxDocsBuildFactory() in Zorg [2] to also checkout
libcxx and build the documentation. This should be controlled by
boolean argument(s) to the function which should be false by default.

3. Finally add a builder by adding an entry to
``_get_documentation_builders()`` [3] that uses your modifications in
``getSphinxDocsBuildFactory()``.

4. Ask Galina to restart the buildbot master

[1]
https://github.com/llvm-mirror/llvm/blob/master/cmake/modules/AddSphinxTarget.cmake
[2]
https://github.com/llvm-mirror/zorg/blob/master/zorg/buildbot/builders/SphinxDocsBuilder.py
[3]
https://github.com/llvm-mirror/zorg/blob/master/buildbot/osuosl/master/config/builders.py#L1083

Hope that helps.

Thanks,
Dan.

On Fri, Jul 31, 2015 at 12:01 AM, Dan Liew <dan at su-root.co.uk>
wrote:
> Hi Eric,
>
> On 20 July 2015 at 10:41, Eric Fiselier <eric at efcs.ca> wrote:
>> Hi All,
>>
>> I'm working on rewriting libc++'s documentation using Sphinx.
>> Hopefully it will be easier to write and maintain documentation using
>> restructured text and not HTML.
>>
>> What steps do I need to take to get libc++ a Sphinx builder and get
>> the required changes made for libcxx.llvm.org?
>
> To add a documentation builder for the buildbot infrastructure here
> are the basic steps.
>
> 0. Check with Dmitri Gribenko (CC'ed) that he is happy to host another
> builder for the libcxx documentation on his build slave.
More than happy to do so.  Feel free to edit the configuration.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at
gmail.com>*/