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.

64–77

Unrelated change?

180–182

Why is this necessary?

306–308

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.

64–77

Yes, it's unrelated.

180–182

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

306–308

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
180–182

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.

tammela added inline comments.Aug 2 2021, 5:59 AM
lldb/docs/use/scripting-reference.rst
572

So I'm guessing some sections are still missing some updates because the Lua functionality is not there yet right?

If so, I would add some note that this is not currently supported in Lua.

This update marks features that are only supported by Python, and adds Lua
example code for using LLDB module.

I think we are getting there, just some more details

lldb/docs/use/scripting-example.rst
822 ↗(On Diff #366494)
lldb/docs/use/scripting-reference.rst
1–2

I'm seeing some references to a "python script" when it should be really just "the following script" or something more neutral.

A quick way to solve this is to search for [Pp]ython and try to rewrite the phrase into something generic

This update makes scripting example more coherent even if Lua parts are added.

This update improves the scripting reference parts.

tammela accepted this revision.Mon, Aug 23, 8:46 AM

LGTM