Page MenuHomePhabricator

Generate LLDB website/documentation from rst with Sphinx
Needs ReviewPublic

Authored by JDevlieghere on Dec 6 2018, 9:00 AM.


Group Reviewers
Restricted Project

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. This patch adds a new target docs-lldb-html when -DLLVM_ENABLE_SPHINX:BOOL is set 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.

Generated html available here :

Diff Detail

Event Timeline

JDevlieghere created this revision.Dec 6 2018, 9:00 AM
brucem added a subscriber: brucem.Dec 6 2018, 9:02 AM
brucem added a comment.Dec 6 2018, 9:07 AM

This sounds great to me.

Perhaps it'd be nice if we could use Sphinx instead of epydoc in the future?

Add more pages

Add another set of pages.

I think this is going to be really nice! Here's a few details I found.


Maybe all < and > should be changed to &lt; and &gt; respectively?
<args> here somehow survives, but all other other angle-brackets content disappears.


Unfortunately all -- turn into one large . Is it possible to disable (or escape each instance)?


Interestingly this turns into (Hope that there are no C functions named **main*)*
There is another case below. BTW do we really need these comments?


Could the * be escaped? Otherwise this turns into a bullet point.


The \ disappears.

serge-sans-paille resigned from this revision.Wed, Jan 9, 7:06 AM

Decided to just use HTML tables for the GDB - LLDB mapping

JDevlieghere marked 5 inline comments as done.Tue, Jan 15, 6:41 PM

Add remaining pages.

JDevlieghere edited the summary of this revision. (Show Details)Tue, Jan 15, 10:27 PM
  • Move the first paragraph of the about page onto the main page.