[lldb-dev] [RFC] Using Sphinx to generate documentation

[Jonas Devlieghere via lldb-dev]

For those interested, I've uploaded the latest version of the generated
HTML:

https://jonasdevlieghere.com/static/lldb/

I'd have to double check but I think that almost everything was ported
over. The biggest issue is that the GDB to LLDB command map is totally
unreadable with the RST generated table. I spent a little time tweaking the
CSS, but this needs some attention. Worst case we'll have to have an HTML
table here.

Theme-wise I went with the one used by clang. I think it's the most
readable and I personally really like the local ToC. The disadvantage is
that it doesn't have a sidebar, so you have to navigate back to "contents"
in the top right corner.

The alternative is the LLVM theme where we can have Sphinx generate the
global ToC in the sidebar. When I tried this it was missing the section
names (e.g. "Goals & Status" as seen on the main page).  Another issue is
that the local ToC gets totally lost beneath it because everything doesn't
fit on the screen. Once I figure out how/if we can include the section
names I'll generate the site with the LLVM theme so people can compare and
give their opinion.

Cheers,
Jonas

On Tue, Jan 8, 2019 at 9:31 AM Jonas Devlieghere <jonas at devlieghere.com>
wrote:

>
>
> On Tue, Jan 8, 2019 at 8:52 AM Stefan Gränitz via lldb-dev <
> lldb-dev at lists.llvm.org> wrote:
>
>> Hi Jonas, I think this is a great effort. Thanks!
>>
>> My current reviews do some small updates on the build page. Hope this
>> doesn't get in conflict with your work?
>>
>
> Thanks for the heads up Stefan. This should be fine, I'll copy over your
> change in the rst files.
>
>
>> Best
>> Stefan
>>
>> On 6. Dec 2018, at 18:02, Jonas Devlieghere via lldb-dev <
>> lldb-dev at lists.llvm.org> wrote:
>>
>> Hi everyone,
>>
>> The current LLDB website is written in HTML which is hard to maintain. We
>> have quite a bit of HTML code checked in which can make it hard to
>> differentiate between documentation written by us and documentation
>> generated by a tool. Furthermore I think text/RST files provide a lower
>> barrier for new or casual contributors to fix or update.
>>
>> In line with the other LLVM projects I propose generating the
>> documentation with Sphix. I created a patch (
>> https://reviews.llvm.org/D55376) that adds a new target docs-lldb-html
>> when -DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages to
>> give an idea of what this would look like in-tree. Before continuing with
>> this rather tedious work I'd like to get feedback form the community.
>>
>> Initially I started with the theme used by Clang because it's a default
>> theme and doesn't require configuration. If we want to keep the sidebar we
>> could use the one used by LLD.
>>
>> Please let me know what you think.
>>
>> Thanks,
>> Jonas
>> _______________________________________________
>> lldb-dev mailing list
>> lldb-dev at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev
>>
>>
>> _______________________________________________
>> lldb-dev mailing list
>> lldb-dev at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/lldb-dev/attachments/20190108/e129511a/attachment.html>