Avoid creating an uncacheable conf variable by using a string instead of
a function reference. Also has the effect of avoiding triggering the
"config.cache" sphinx warning.
Requires myst_parser 0.19.0 (specifically
https://github.com/executablebooks/MyST-Parser/pull/696) which is over a
year old by now. Do we mandate any minimum version for these
dependencies?
That aren't the generated `python_api/` pages.
This button is a pencil icon at the top right of the page and takes you
to a GitHub page where you can edit the content, assuming you have a
fork already. If not it tells you how to make one.
This is hardcoded to the llvm-project URL and main branch. So folks will
need a downstream patch if they want to change that.
For the upstream repo, main is right because even if a release branch
was open for PRs, it would only be for cherry picks from main.
The icon isn't as obvious as the "edit on GitHub" icons seen elsewhere
but it's built in, and we could change it later if we wanted to.
RST is powerful but usually too powerful for 90% of what we need it for.
Markdown is easier to edit and can be previewed easily without building
the entire website.
This copies what llvm does already, making myst_parser optional if you
only want man pages.
Previously we had Markdown enabled in
8b95bd3310c126e76e0714bea6003a9b1aa739fb but that got reverted. That did
this in a different way but I've gone with the standard llvm set this
time.
I intend the first Markdown pages to be the remote protocol extension
docs, as they are not in any set format right now.
This patch re-lands f0731d5b61ba with more fixes and improvements.
First, this patch removes `__eq__` implementations from classes that
didn't implemented `operator!=` on the C++ implementation.
This patch removes sphinx document generation for special members such
as `__len__`, since there is no straightforward way to skip class that
don't implement them. We also don't want to introduce a change in
behavior by implementing artifical special members for classes that are
missing them.
Finally, this patch improve the ergonomics of some classes by
implementing special members where it makes sense, i.e. `hex(SBFrame)`
is equivalent to `SBFrame.GetPC()`.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This reverts 3 commit:
- f0731d5b61ba798e6d5a63a92d9228010e5a3b50.
- 8e0a087571a31057bb98939e3ada73227bed83c7.
- f2f5d6fb8d53bc4bd93a3d4e110134ed017b636f.
This changes were introduced to silence the warnings that are printed
when generating the lldb module documentation for the website but it
changed the python bindings and causes test failures on the macos bot:
https://green.lab.llvm.org/green/job/lldb-cmake/59438/
We will have to consider other options to silence these warnings.
This reverts commit 18f1c1ace7a6099f3e8e56cf4b81aa0f64a7dd23 and fix the
build failure issues introduced because of the `STRING_EXTENSION_OUTSIDE`
swig macros.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch does various things to silence the warnings that show up when
generating the website documentation.
First, this patch adds the missing definition for special member methods
in every SBAPI class. If the class cannot implement one of the special
member method, we just define it as a null operation (pass).
This should fix the following warnings:
```
WARNING: missing attribute __int__ in object lldb.SB*
WARNING: missing attribute __len__ in object lldb.SB*
WARNING: missing attribute __hex__ in object lldb.SB*
WARNING: missing attribute __oct__ in object lldb.SB*
WARNING: missing attribute __iter__ in object lldb.SB*
```
Then, it un-skips the various `static` methods that we didn't generate
the methods for, since it's not necessary thanks to the automod-api module.
Finally, this comments out the `_static` directory in the sphinx config,
since we don't need it anymore.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch reverts the lldb website revamp (eea8874) since the `furo` theme
that we use is not installed on the publisher bot. The prevents other
website from getting there documentation updated.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
These were useful primarily for the Python 2 to 3 transition. Python 2
is no longer supported so these are no longer necessary.
Differential Revision: https://reviews.llvm.org/D157759
This is an ongoing series of commits that are reformatting our Python
code. Reformatting is done with `black` (23.1.0).
If you end up having problems merging this commit because you have made
changes to a python file, the best way to handle that is to run `git
checkout --ours <yourfile>` and then reformat it with black.
RFC: https://discourse.llvm.org/t/rfc-document-and-standardize-python-code-style
Differential revision: https://reviews.llvm.org/D151460
The sphinx-automodapi extension requires that the generated RST files
live next to the index file. This means that we generate them in the
source directory rather than the build directory. This patch ensures
these files are removed again when sphinx finishes its build.
The proper solution to this problem would be to move everything in the
doc folder from the source directory to the build directory before
generating the docs.
I believe that old RST files being kept around is the reason that the
Python API references on the website isn't getting updated. This patch
is meant as a speculative fix and a way to confirm that.
The recommonmark package is no longer required since all the documents
have been converted to .rst. Remove the related support code from
docs/conf.py.
Differential Revision: https://reviews.llvm.org/D112612
The current LLDB Python docs are missing documentation for all the special
members such as conversion functions (`__int__`) and other special functions
(`__len__`).
The reason for that is that the `automodapi` plugin we're using to generate the
*.rst files simply doesn't emit them. There doesn't seem to be any config option
to enable those in `automodapi` and it's not even clear why they are filtered. I
assume the leading underscore in their names makes them look like private
methods.
This patch just forcibly adds a few selected special members functions to the
list of functions that sphinx should always document. This will cause sphinx to
warn if a class doesn't have one of those functions but it's better than not
having them documented.
The main motivation here is that since `SBAddress.__int__` is one of the few
functions that is only available in the embedded Python REPL which would be good
to have in the public documentation.
Fixes rdar://64647665
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D105480
In D94489 we changed the way we build the docs and now have some additional
dependencies to generate the Python API docs. As the same sphinx project is
generating the man pages for LLDB it should have in theory the same setup code
that sets up the mocked LLDB module.
However, as we don't have that setup code the man page generation just fails as
there is no mocked LLDB module and the Python API generation errors out.
The man page anyway doesn't cover the Python API so I don't think there is any
point of going through the whole process (and requiring the sphinx plugins) just
to generate the (eventually unused) Python docs.
This patch just skips the relevant Python API generation when we are building
the man page.
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D98441
For unknown reasons the alabaster theme on the docs server is always generating
a GitHub link in the side bar. Beside the privacy problems of having an iframe
to some third-party service, we never configured any GitHub integration so
this button just links to the GitHub main site.
The button generation should be disabled by default, but as that's apparently
not true in the alabaster theme on the server, this patch tries working around
the issue by just explicitly turning off the GitHub integration.
This patch implements a filter that post-processes some of the generated RST sources
of the Python API docs. I mainly want to avoid two things:
1. Filter out all the inheritance boilerplate that just keeps mentioning for
every class that it inherits from the builtin 'object'. There is no inheritance
in the SB API.
2. More importantly, removes the SWIG generated `thisown` attribute from the
public documentation. I don't think we want users to mess with that attribute
and this is probably causing more confusion than it would help anyone. It also
makes the documentation for some smaller classes more verbose than necessary.
This patch just uses the sphinx event for reading source and removes the parts
that we don't want in documentation.
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D94967
sphinx processes text in backticks depending on what 'role' it has (e.g.,
`:code:\`blub\`` -> role is `code`). If no role is provided, the default role is
taken which is right now using the default value of `content`. `content` only
really makes the text cursive which isn't really useful for anything right now.
Sphinx recommends using the `any` role by default [1] as that turns text in
backticks without an explicit roles into some kind of smart reference. If we did
this in LLDB, then we could just reference SB API classes by doing `\`SBValue\``
instead of typing out the rather verbose `:py:class:`/`:py:func:`/... role
before each reference. This would be especially nice when writing the SB API
docs itself as we constantly have to reference other classes.
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-any
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D94899
The build server should now have the missing dependencies.
Original summary:
Currently LLDB uses epydoc to generate the Python API reference for the website.
epydoc however is unmaintained since more than a decade and no longer works with
Python 3. Also whatever setup we had once for generating the documentation on
the website server no longer seems to work, so the current website documentation
has been stale since more than a year.
This patch replaces epydoc with sphinx and its automodapi plugin that can
generate Python API references. LLVM already uses sphinx for the rest of the
documentation, so this way we are more consistent with the rest of LLVM. The
only new dependency is the automodapi plugin for sphinx.
This patch effectively does the following things:
* Remove the epydoc code.
* Make a new dummy Python API page in our website that just calls the Sphinx
command for generated the API documentation.
* Add a mock _lldb module that is only used when generating the Python API.
This way we don't have to build all of LLDB to generate the API reference.
Some notes:
* The long list of skips is necessary due to boilerplate functions that SWIG
is generating. Sadly automodapi is not really scriptable from what I can see,
so we have to blacklist this stuff manually.
* The .gitignore change because automodapi wants a subfolder of our
documentation directory to place generated documentation files there. The path
is also what is used on the website, so we can't really workaround this
(without copying the whole `docs` dir somewhere else when we build).
* We have to use environment variables to pass our build path to our sphinx
configuration. Sphinx doesn't support passing variables onto that script.
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D94489
Currently LLDB uses epydoc to generate the Python API reference for the website.
epydoc however is unmaintained since more than a decade and no longer works with
Python 3. Also whatever setup we had once for generating the documentation on
the website server no longer seems to work, so the current website documentation
has been stale since more than a year.
This patch replaces epydoc with sphinx and its automodapi plugin that can
generate Python API references. LLVM already uses sphinx for the rest of the
documentation, so this way we are more consistent with the rest of LLVM. The
only new dependency is the automodapi plugin for sphinx.
This patch effectively does the following things:
* Remove the epydoc code.
* Make a new dummy Python API page in our website that just calls the Sphinx
command for generated the API documentation.
* Add a mock _lldb module that is only used when generating the Python API.
This way we don't have to build all of LLDB to generate the API reference.
Some notes:
* The long list of skips is necessary due to boilerplate functions that SWIG
is generating. Sadly automodapi is not really scriptable from what I can see,
so we have to blacklist this stuff manually.
* The .gitignore change because automodapi wants a subfolder of our
documentation directory to place generated documentation files there. The path
is also what is used on the website, so we can't really workaround this
(without copying the whole `docs` dir somewhere else when we build).
* We have to use environment variables to pass our build path to our sphinx
configuration. Sphinx doesn't support passing variables onto that script.
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D94489
This enables support for writing LLDB documentation in markdown in
addition to reStructured text. We already had documentation written in
markdown (StructuredDataPlugins and DarwinLog) which will now also be
available on the website.
This patch replaces the existing out-of-date man page for lldb and
replaces it with an RST file from which sphinx generates the actual
troff file. This is similar to how man pages are generated for the rest
of the LLVM utilities.
The man page is generated by building the `docs-lldb-man` target.
Differential revision: https://reviews.llvm.org/D70514
This returns the look & feel of the Sphinx-generated LLDB website to
the original pre-Sphinx layout.
Differential Revision: https://reviews.llvm.org/D61913
llvm-svn: 360819
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.
In line with the other LLVM projects, I propose generating the
documentation with Sphix. I think text/rst files provide a lower barrier
for new or casual contributors to fix or update.
This patch adds a copy of the LLDB website and documentation in
reStructuredText. It also adds a new ninja target `docs-lldb-html` when
-DLLVM_ENABLE_SPHINX:BOOL is enabled.
This is the first step in having the website and documentation being
generated from the repository, rather than having the output checked-in
under the www folder. During the hopefully short transition period,
please also update the reStructuredText files when modifying the
website.
Differential revision: https://reviews.llvm.org/D55376
llvm-svn: 352644
