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
Summary:
This diff introduces .rst files, Sphinx config, and a CMake target
for building clang man pages. This will deprecate the existing .pod-
based man page, and will integrate nicely with CMake. This diff does
not remove the existing man page; that will be done in a follow-up
once packagers have had a chance to react to the change.
For now, only clang(1) has been done; others can be added over time
by dropping additional files into the docs/CommandGuide directory.
The index page for CommandGuide has been copied from LLVM's
docs/CommandGuide.
The man page itself is mostly the same, with a few minor cosmetic
changes. The only major change is the SYNOPSIS section. I was unable
to get .rst/Sphinx produce the same style as in the existing man page.
Instead, I changed it to match the LLVM tools' relatively simple style.
To build the man pages, use the "docs-clang-man" target if building
with CMake. Otherwise, use "make -f Makefile.sphinx man".
Reviewers: cmatthews, silvas
Subscribers: dim, gaeke, beanz, cfe-commits
Differential Revision: http://reviews.llvm.org/D10562
llvm-svn: 241037
r203272 enables generation of a Qt Compressed Help file for the LLVM source
code.
As a consequence, this change brings the same capabilities to Clang while
reusing these two variables:
LLVM_ENABLE_DOXYGEN_QT_HELP
LLVM_DOXYGEN_QHELPGENERATOR_PATH
and adding
CLANG_DOXYGEN_QCH_FILENAME="org.llvm.clang.qch"
CLANG_DOXYGEN_QHP_NAMESPACE="org.llvm.clang"
CLANG_DOXYGEN_QHP_CUST_FILTER_NAME="Clang ${CLANG_VERSION}"
CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS="Clang,${CLANG_VERSION}"
Patch by Konrad Kleine.
llvm-svn: 203801
Nico Weber