Page MenuHomePhabricator

[lldb][docs] Add reference docs for Lua scripting
Needs ReviewPublic

Authored by siger-young on Jun 14 2021, 10:44 PM.

Details

Summary

Add a basic reference page for Lua scripting, as a counterpart to section "Python Reference".

Diff Detail

Event Timeline

siger-young created this revision.Jun 14 2021, 10:44 PM
siger-young requested review of this revision.Jun 14 2021, 10:44 PM
Herald added a project: Restricted Project. · View Herald TranscriptJun 14 2021, 10:44 PM

Instead of copying the text from the Python page, I was actually thinking whether we should make the 'scripting' page more generic and just add the language-specific examples for Python and Lua there. I am not sure what's the best way to do that visually though with RST. We could just go for raw HTML and use a tab switcher like this:

Also I don't think a lot of LLDB distributors include Lua at the moment, so I think that should be pointed out at some point, otherwise this leads to confusion.

lldb/docs/use/lua-reference.rst
21 ↗(On Diff #352046)

I think that only works if Lua is the default? script -l lua -- seems what should work for all users independently of the default/config (unless Lua is disabled of course)

Instead of copying the text from the Python page, I was actually thinking whether we should make the 'scripting' page more generic and just add the language-specific examples for Python and Lua there. I am not sure what's the best way to do that visually though with RST. We could just go for raw HTML and use a tab switcher like this:

In fact, the same idea also occurred to me before. I think it's also achievable by a plugin sphinx-code-tabs.

I will try to improve the whole scripting section in this kind of way.

Also I don't think a lot of LLDB distributors include Lua at the moment, so I think that should be pointed out at some point, otherwise this leads to confusion.

Yes. I will put some tips at the beginning of the docs.

I will update the patch in few weeks.

In fact, the same idea also occurred to me before. I think it's also achievable by a plugin sphinx-code-tabs.

I like that idea! We do have to give the peopler running the docs bot a heads up though that they need to install that plugin, but I can take care of that when everyone agrees this is ready to land. Thanks!

Reference page for Python and Lua is ready. A new sphinx extension "sphinx-tabs"
is added to enable users switching the language.

I'm a little suspicious about the changes to conf.py. Can you explain why they're necessary and what they're fixing?

lldb/docs/conf.py
32–33

Why is this necessary? It sounds like CMake should be setting this variable.

63–77

Unrelated change?

183–184

Why is this necessary?

309–310

Unrelated whitespace change?

siger-young added inline comments.Jun 21 2021, 11:56 AM
lldb/docs/conf.py
32–33

At the beginning, I was using ninja lldb-docs-html to build the docs. But it seems that it will build all of the docs each time it runs. It wastes some time, so I turn to sphinx-build command to build it, thus the env might become None. If extension sphinx_tabs.tabs is added, None value in sys.path will affect its importing.

63–77

Yes, it's unrelated.

183–184

When I built the docs using the html_context, the final pages only include lldb.css, missing files from theme e.g. alabaster.css.

309–310

Yes.

Rebase two commits.

There are a bunch of unrelated changes in this patch. Can you please drop them or split them off into a separate patch?

lldb/docs/conf.py
183–184

Does this not break building the docs with ninja lldb-docs-html?

JDevlieghere requested changes to this revision.Jul 1 2021, 9:35 AM
This revision now requires changes to proceed.Jul 1 2021, 9:35 AM

Add integrated pages (Lua + Python) for scripting docs.