This is a new draft of D28234. I previously did the unorthodox thing of
pushing to it when I wasn't the original author, but since this version
- Uses `GNUInstallDirs`, rather than mimics it, as the original author
was hesitant to do but others requested.
- Is much broader, effecting many more projects than LLVM itself.
I figured it was time to make a new revision.
I am using this patch (and many back-ports) as the basis of
https://github.com/NixOS/nixpkgs/pull/111487 for my distro (NixOS). It
looked like people were generally on board in D28234, but I make note of
this here in case extra motivation is useful.
---
As pointed out in the original issue, a central tension is that LLVM
already has some partial support for these sorts of things. For example
`LLVM_LIBDIR_SUFFIX`, or `COMPILER_RT_INSTALL_PATH`. Because it's not
quite clear yet what to do about those, we are holding off on changing
libdirs and `compiler-rt`. for this initial PR.
---
On the advice of @lebedev.ri, I am splitting this up a bit per
subproject, starting with LLVM. To allow it to be more easily reviewed. This and the subsequent patch must be landed together, as this will not build alone. But the rest can be landed on their own.
Reviewed By: compnerd
Differential Revision: https://reviews.llvm.org/D100810
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
Do not enforce recommonmark dependency if sphinx is called to build
manpages. In order to do this, try to import recommonmark first
and do not configure it if it's not available. Additionally, declare
a custom tags for the selected builder via CMake, and ignore
recommonmark import failure when 'man' target is used.
This will permit us to avoid the problematic recommonmark dependency
for the majority of Gentoo users that do not need to locally build
the complete documentation but want to have tool manpages.
Differential Revision: https://reviews.llvm.org/D83161
Summary:
This is an attempt to simply the process of building the clang
documentation, which should help avoid some of the recent issues we've
had generating the documentation for the website.
The html documentation for clang is generated by sphinx from the
reStructuredText (rst) files we have in the clang/docs directory.
There are also some rst files that need to be generated by TableGen,
before they can be passed to sphinx. Prior to this patch we were not
generating those rst files as part with the build system and they had to be
generated manually.
This patch enables the automatic generation of these rst files, but
since they are generated at build time the cannot be placed in the
clang/docs directory and must go into the cmake build directory.
Unfortunately sphinx does not currently support multiple source
directories[1], so in order to be able to generate the full
documentation, we need to work around this by copying the
rst files from the clang/docs into the build directory before
generating the html documentation.
[1] https://github.com/sphinx-doc/sphinx/issues/3132
Reviewers: rsmith, aaron.ballman, beanz, smeenai, phosek, compnerd, mgorny, delcypher
Reviewed By: mgorny, delcypher
Subscribers: delcypher, merge_guards_bot, mgorny, llvm-commits, cfe-commits
Tags: #clang, #llvm
Differential Revision: https://reviews.llvm.org/D72875
Add install targets as necessary to include all files normally installed
in LLVM_DISTRIBUTION_COMPONENTS. This includes targets for Sphinx docs,
opt-viewer Python modules and TableGens.
Differential Revision: https://reviews.llvm.org/D68339
llvm-svn: 373482
Modify add_sphinx_target() to include the project name alongside builder
in Sphinx doctree directory. This aims to avoid crashes due to race
conditions between multiple Sphinx instances running in parallel that
attempt to create or read that directory simultaneously.
This problem has originally been addressed in r283188. However, that
commit presumed that there will be only one target per builder being
run. However, r314863 introduced a second manpage target, reintroducing
the race condition.
Differential Revision: https://reviews.llvm.org/D40656
llvm-svn: 319461
Summary:
This was broken by r302499. Configuring with -DLLVM_BUILD_DOCS=ON would
cause the docs-llvm-man target not to be created.
Reviewers: anemet, beanz
Reviewed By: anemet
Subscribers: llvm-commits, mgorny
Differential Revision: https://reviews.llvm.org/D33146
llvm-svn: 303042
When CMAKE_INSTALL_MANDIR isn't defined it ends up attempting to install
the man pages under "/man1" and we really don't want to accidentally install
stuff at the filesystem root.
llvm-svn: 297545
Include component in install rules for Sphinx targets. Based on
a similar suggestion for other doc targets in D24935.
Differential Revision: https://reviews.llvm.org/D24982
llvm-svn: 288656
Use separate doctrees between different Sphinx builders in order to
prevent race condition issues due to multiple Sphinx instances accessing
the same doctree cache in parallel.
Bug: https://llvm.org/bugs/show_bug.cgi?id=23781
Differential Revision: https://reviews.llvm.org/D23755
llvm-svn: 283188
The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html",
"docs-llvm-man" targets but does not build them by default. The
following CMake options have been added that control what targets are
made available
SPHINX_OUTPUT_HTML
SPHINX_OUTPUT_MAN
If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will
be built by default and if ``make install`` is run then docs-llvm-html
and docs-llvm-man will be installed (tested on Linux only).
The add_sphinx_target function is in its own file so it can be included
by other projects that use Sphinx for their documentation.
Patch by Daniel Liew <daniel.liew@imperial.ac.uk>!
llvm-svn: 206655
Med Ismail Bennani