This is an archive of the discontinued LLVM Phabricator instance.

Generate LLDB website/documentation from rst with Sphinx
ClosedPublic

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

Details

Summary

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 : https://jonasdevlieghere.com/static/lldb/index.html

Diff Detail

Repository
rL LLVM

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.

docs/use/map.rst
28 ↗(On Diff #179738)

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

30 ↗(On Diff #179738)

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

236 ↗(On Diff #179738)

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?

330 ↗(On Diff #179738)

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

858 ↗(On Diff #179738)

The \ disappears.

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

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

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

Add remaining pages.

JDevlieghere edited the summary of this revision. (Show Details)Jan 15 2019, 10:27 PM
  • Move the first paragraph of the about page onto the main page.
davide accepted this revision.Jan 29 2019, 12:54 PM

LGTM

This revision is now accepted and ready to land.Jan 29 2019, 12:54 PM
jingham accepted this revision.Jan 29 2019, 2:46 PM

LGTM

labath accepted this revision.Jan 29 2019, 11:56 PM

Let's ship it. :)

This revision was automatically updated to reflect the committed changes.
labath added a comment.Mar 5 2019, 5:28 AM

So, what's the state of this now? The rst files have been committed, but we seem to still have the old html files lying around (and AFAICT, http://lldb.llvm.org is still serving from those). I am trying make an update to the architecture docs, but I am confused as to which version should I be editting..

Herald added a project: Restricted Project. · View Herald TranscriptMar 5 2019, 5:28 AM
Herald added a subscriber: jdoerfert. · View Herald Transcript
thakis added a subscriber: thakis.Apr 21 2019, 9:22 AM

This (I'm guessing) broke https://lldb.llvm.org/lldb-gdb.html which is still present in many search indices. Could we make that page redirect to whatever is the new replacement? (https://www.w3.org/Provider/Style/URI etc)