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

Wed Jan 9 04:09:31 PST 2019

Hey Jonas that looks great! And what a nice way to do the review.

Two of the pages from "RESOURCES" are in the new docs now: Testing LLDB and The SB API Coding Rules
Will they be removed from the root page and/or do the others follow?

Added a few notes on escape characters to the review.

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

GDB to LLDB map is one of  the most viewed pages in the docs right? I had a look and got the below result with a few CSS tweaks in the layout "debugger":

    p, blockquote { margin-top: 0px; margin-bottom: 0px; }
    tr.row-even { background: #eee; }
    tr.row-odd td { font-family: monospace; padding-bottom: 15px; }
    table.docutils { width: 100%; }

The last one sets full width on all tables. About columns having content-specific width, I am not sure. Might be interesting to see with a 50/50 setting in all <colgroup>'s.
Maybe we could also get rid of the column headers? The prompts say it all :)

> On 8. Jan 2019, at 19:12, Jonas Devlieghere <jonas at devlieghere.com> wrote:
> 
> For those interested, I've uploaded the latest version of the generated HTML:
> 
> https://jonasdevlieghere.com/static/lldb/ <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 <mailto: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 <mailto: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 <mailto: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 <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 <mailto:lldb-dev at lists.llvm.org>
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev <http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev>
> 
> _______________________________________________
> lldb-dev mailing list
> lldb-dev at lists.llvm.org <mailto:lldb-dev at lists.llvm.org>
> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev <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/20190109/3f8517cd/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gdblldbmap-css-tweak.png
Type: image/png
Size: 83295 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/lldb-dev/attachments/20190109/3f8517cd/attachment-0001.png>