LLDB API Docs on the WWW?

Hi all,

One of the great things about LLDB is the API — both C++ and Python. Recently, I added some targets that generate HTML documentation for the Python module and C++ headers, but it's still somewhat cumbersome to use locally:

$ ninja lldb-python-doc lldb-cpp-doc
$ firefox tools/lldb/doc/.………./index.html
<navigate using links and other antiquated searches>

Whereas for LLVM docs, I just google "llvm module" and the first hit is the right documentation page. It would be great if I could just google "lldb SBTarget" and see the SBTarget docs.

So, do people think this would be a good idea; to have LLDB HTML docs somewhere Google can find them?

If so, does manually checking in some directories of generated HTML into lldb/www sound ok? Eventually, it would be nice to have the docs auto-generated by a buildbot or equivalent, but for the time being I think this is sufficient.

Also, what about internals? Do we want the docs to contain stuff in lldb/source or just lldb/include? It does make a difference on the final size of the docs:

With internals ('include' + 'source directories'): ~574MB
Without internals (only 'include' directory): ~157MB

Most of the above is png inheritance diagrams…

As for the python stuff, when generated by epydoc, is a little bit smaller and weighs in at only 14MB

Anyways, let me know what you guys think. Is www the right place to put CPP/Python reference docs? Should I exclude internals?

Cheers,
Dan

Hi all,

One of the great things about LLDB is the API — both C++ and Python. Recently, I added some targets that generate HTML documentation for the Python module and C++ headers, but it's still somewhat cumbersome to use locally:

$ ninja lldb-python-doc lldb-cpp-doc
$ firefox tools/lldb/doc/.………./index.html
<navigate using links and other antiquated searches>

Whereas for LLVM docs, I just google "llvm module" and the first hit is the right documentation page. It would be great if I could just google "lldb SBTarget" and see the SBTarget docs.

So, do people think this would be a good idea; to have LLDB HTML docs somewhere Google can find them?

If so, does manually checking in some directories of generated HTML into lldb/www sound ok? Eventually, it would be nice to have the docs auto-generated by a buildbot or equivalent, but for the time being I think this is sufficient.

This would be nice. Versioning is a bit of an issue as there may be calls in the top of tree source that may not exist in say the 3.x LLDB packages, or in the current Xcode releases.

Also, what about internals? Do we want the docs to contain stuff in lldb/source or just lldb/include? It does make a difference on the final size of the docs:

With internals ('include' + 'source directories'): ~574MB
Without internals (only 'include' directory): ~157MB

Most of the above is png inheritance diagrams…

As for the python stuff, when generated by epydoc, is a little bit smaller and weighs in at only 14MB

Anyways, let me know what you guys think. Is www the right place to put CPP/Python reference docs? Should I exclude internals?

I vote to exclude internals and only publish the "lldb/include/API" headers (lldb::SB*) from top of tree and not worry about versioning, just always show the latest and greatest.

Not sure if we can automatically detect any changes to lldb/include/API/*.h will cause a SVN server side script to kick off and regenerate the doxygen headers and check them it automatically? Then you would always have a current set of documentation locally on your machine for your checked out LLDB?

Greg

I vote to exclude internals and only publish the "lldb/include/API"
headers (lldb::SB*) from top of tree and not worry about versioning, just
always show the latest and greatest.

If we only want the SB* classes, the overall size of the C++ reference
goes down to 12MB, which makes me feel a lot better :slight_smile:

Not sure if we can automatically detect any changes to
lldb/include/API/*.h will cause a SVN server side script to kick off and
regenerate the doxygen headers and check them it automatically? Then you
would always have a current set of documentation locally on your machine
for your checked out LLDB?

I think that makes sense. If I'm not mistaken LLVM docs are updated in a
similar fashion, but the HTML is not checked in. Does anyone know who
maintains the LLVM docs, or who set them up? They might have some input
here..

Dan