[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.

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

Hi Eric,

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.

More than happy to do so. Feel free to edit the configuration.

Dmitri

Hi Tanya,

Pinging this patch (with the proper lists attached). It's blocking
other work regarding libc++ docs.

Libc++ is setup and ready to generate libcxx.llvm.org/docs.
I have followed the instructions that Dan provided in this thread (see
http://lists.cs.uiuc.edu/pipermail/cfe-dev/2015-July/044465.html).

You can build libc++ docs using CMake like any other LLVM project.
Configure CMake using -DLLVM_ENABLE_SPHINX=ON and build using `make
docs-libcxx-html`.

Please let me know if you have any trouble setting this up.
PS Sorry to all those that got multiple copies of this email.

/Eric