[lldb-dev] LLDB API Docs on the WWW?

[Greg Clayton]

On Jun 25, 2013, at 11:41 AM, "Malea, Daniel" <daniel.malea at intel.com> wrote:

> 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

> 
> Cheers,
> Dan
> 
> _______________________________________________
> lldb-dev mailing list
> lldb-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/lldb-dev