[RFC] Using Sphinx to generate documentation

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

I like this a lot!

I commented on the patch since I didn’t see this thread at the time, but it’d be interesting to perhaps replace Epydoc with Sphinx as well.

  • Bruce

Woohoo!

Just to be clear, is the idea to still check in the resulting html files to remain compatible with how http://lldb.llvm.org (I have no idea who maintains that) works, or do you want to change that as well (e.g., by having the server generate the html files locally).

pl

I think if we want to actually lower the entry barrier for
contributing/fixing things on the website, then the server should do
this. From what I know the other LLVM projects also generate the HTML
on the server (at least I've never seen anyone commit generated HTML
files), so this hopefully shouldn't be too complicated.

I think in general this approach is really nice. Thanks a lot for the
work @Jonas!

- Raphael

I think if we want to actually lower the entry barrier for
contributing/fixing things on the website, then the server should do
this. From what I know the other LLVM projects also generate the HTML
on the server (at least I’ve never seen anyone commit generated HTML
files), so this hopefully shouldn’t be too complicated.

Agree. Also, there’s enough differences between the generated HTML for various versions of the tools that having it happen on the server would be good.

I think in general this approach is really nice. Thanks a lot for the
work @Jonas!

Indeed!

  • Bruce

I think if we want to actually lower the entry barrier for
contributing/fixing things on the website, then the server should do
this. From what I know the other LLVM projects also generate the HTML
on the server (at least I’ve never seen anyone commit generated HTML
files), so this hopefully shouldn’t be too complicated.

Yes, I definitely want to generate it. It should be straightforward to add a build bot that does this. I’ll see what is needed for this while I continue porting the other pages.

I’d like to have the doxygen and python documentation generated as well. The one that’s currently hosted on llvm.org is several years old, last time I checked.

Agree. Also, there’s enough differences between the generated HTML for various versions of the tools that having it happen on the server would be good.

I’d have to double check how llvm

I think in general this approach is really nice. Thanks a lot for the
work @Jonas!

Indeed!

My pleasure! I’m happy to see the positive reception here.

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?

Best
Stefan

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.

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

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 's.
Maybe we could also get rid of the column headers? The prompts say it all :slight_smile:

gdblldbmap-css-tweak.png

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.

gdblldbmap-css-tweak.png