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

Wed Jan 9 08:52:01 PST 2019

On Wed, Jan 9, 2019 at 4:09 AM Stefan Gränitz <sgraenitz at apple.com> wrote:

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

Thanks!

> 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%; }
>
>
Nice. I've added a custom class to these tables so we can limit these
changes to only this table. I think this looks pretty good (you might have
to clear your cache): https://jonasdevlieghere.com/static/lldb/use/map.html

I also managed to fix the column width, except for the first table. I'll
have another look soon.

> 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/
>
> 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/20190109/99b693c0/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/99b693c0/attachment-0001.png>