t-tye created this revision.
t-tye added a reviewer: scott.linder.
Herald added subscribers: libcxx-commits, mgorny.
Herald added a reviewer: bollu.
Herald added a reviewer: MaskRay.
Herald added a reviewer: sscalpone.
Herald added a project: libunwind.
Herald added a reviewer: libunwind.
t-tye requested review of this revision.
Herald added a reviewer: jdoerfert.
Herald added subscribers: cfe-commits, llvm-commits, openmp-commits,
lldb-commits, sstefan1.
Herald added projects: clang, LLDB, libc++, OpenMP, LLVM, clang-tools-extra.
Herald added a reviewer: libc++.
Add support for Sphinx docx builder. Requires Sphinx docx builder to be
installed using `pip install docxbuilder`.
Added `SPHINX_OUTPUT_DOCX` CMake variable to control generation of docx
documentation. Defaults to `OFF`.
Added `<project>_INSTALL_SPHINX_DOCX_DIR` CMake variable to control where docx
files are installed. Defaults to `share/doc/<project>/<project>.docx`.
Documented new CMake variables in `llvm/docs/CMake.rst`.
Updated description of building documentation is `lld/docs/sphinx_intro.rst`,
`lldb/docs/resources/build.rst`, `llvm/docs/README.txt`, and
`openmp/docs/README.txt`,
Update `clang/docs/CMakeLists.txt` for Sphinx man and docx builders to ensure
.td generated .rst files are available to prevent warnings of missing rst files.
Minor CMake cleanups.
Added `docx` as an additional target for the documentation make.bat scripts.
Added `docx` as an additional target rule in the Makefile.sphinx files.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D106339
Files:
clang-tools-extra/docs/CMakeLists.txt
clang-tools-extra/docs/conf.py
clang-tools-extra/docs/make.bat
clang/docs/CMakeLists.txt
clang/docs/Makefile.sphinx
clang/docs/analyzer/conf.py
clang/docs/analyzer/make.bat
clang/docs/conf.py
clang/docs/make.bat
flang/docs/CMakeLists.txt
flang/docs/conf.py
libcxx/docs/CMakeLists.txt
libcxx/docs/Makefile.sphinx
libcxx/docs/conf.py
libunwind/docs/CMakeLists.txt
libunwind/docs/conf.py
lld/docs/CMakeLists.txt
lld/docs/conf.py
lld/docs/make.bat
lld/docs/sphinx_intro.rst
lldb/docs/CMakeLists.txt
lldb/docs/conf.py
lldb/docs/resources/build.rst
llvm/cmake/modules/AddSphinxTarget.cmake
llvm/cmake/modules/FindSphinx.cmake
llvm/docs/CMake.rst
llvm/docs/CMakeLists.txt
llvm/docs/Makefile.sphinx
llvm/docs/README.txt
llvm/docs/conf.py
llvm/docs/make.bat
openmp/docs/CMakeLists.txt
openmp/docs/README.txt
openmp/docs/conf.py
polly/docs/CMakeLists.txt
polly/docs/conf.py
Index: polly/docs/conf.py
===================================================================
--- polly/docs/conf.py
+++ polly/docs/conf.py
@@ -28,6 +28,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: polly/docs/CMakeLists.txt
===================================================================
--- polly/docs/CMakeLists.txt
+++ polly/docs/CMakeLists.txt
@@ -98,6 +98,9 @@
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man polly)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx polly)
+ endif()
endif()
endif()
Index: openmp/docs/conf.py
===================================================================
--- openmp/docs/conf.py
+++ openmp/docs/conf.py
@@ -28,6 +28,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: openmp/docs/README.txt
===================================================================
--- openmp/docs/README.txt
+++ openmp/docs/README.txt
@@ -1,5 +1,5 @@
OpenMP LLVM Documentation
-==================
+=========================
OpenMP LLVM's documentation is written in reStructuredText, a lightweight
plaintext markup language (file extension `.rst`). While the
@@ -14,11 +14,15 @@
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
make
- $BROWSER <build-dir>/projects/openmp/docs//html/index.html
+ $BROWSER <build-dir>/projects/openmp/docs/html/index.html
-The mapping between reStructuredText files and generated documentation is
-`docs/Foo.rst` <-> `<build-dir>/projects/openmp/docs//html/Foo.html` <->
-`https://openmp.llvm.org/docs/Foo.html`.
+The correspondence between reStructuredText files and generated HTML pages is:
+
+LLVM project
+ `llvm/docs/Foo.rst` <-> `<build-dir>/docs/html/Foo.html` <-> `<install-dir>/share/doc/llvm/html/Foo.html` <-> `https://llvm.org/docs/Foo.html`
+
+Other projects
+ `<project>/docs/Foo.rst` <-> `<build-dir>/tools/<project>/docs/html/Foo.html` <-> `<install-dir>/share/doc/<project>/html/Foo.html`<-> `https://<project>.llvm.org/docs/Foo.html`
If you are interested in writing new documentation, you will want to read
`llvm/docs/SphinxQuickstartTemplate.rst` which will get you writing
@@ -26,7 +30,7 @@
reStructuredText markup syntax.
Manpage Output
-===============
+==============
Building the manpages is similar to building the HTML documentation. The
primary difference is to use the `man` makefile target, instead of the
@@ -36,10 +40,41 @@
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
make
- man -l >build-dir>/docs/man/FileCheck.1
+ man -l <build-dir>/docs/man/FileCheck.1
+
+The correspondence between reStructuredText files and generated man pages is:
+
+LLVM project
+ `llvm/docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
+
+Other projects
+ `<project>/docs/CommandGuide/Foo.rst` <-> `<build-dir>/tools/<project>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
-The correspondence between .rst files and man pages is
-`docs/CommandGuide/Foo.rst` <-> `<build-dir>/projects/openmp/docs//man/Foo.1`.
These .rst files are also included during HTML generation so they are also
-viewable online (as noted above) at e.g.
-`https://openmp.llvm.org/docs/CommandGuide/Foo.html`.
+viewable online:
+
+LLVM project
+ `https://openmp.llvm.org/docs/CommandGuide/Foo.html`
+
+Other projects
+ `https://<project>.llvm.org/docs/CommandGuide/Foo.html`
+
+DOCX Output
+===========
+
+Building the DOCX files is similar to building the HTML documentation. The
+primary difference is to use the `docx` makefile target, instead of the
+default (which is `html`). Sphinx then produces the DOCX files in the
+directory `<build-dir>/docs/docx/`.
+
+ cd <build-dir>
+ cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_DOCX=true <src-dir>
+ make
+
+The correspondence between reStructuredText files and generated DOCX files is:
+
+LLVM project
+ `llvm/docs/index.rst` <-> `<build-dir>/docs/docx/LLVM.docx` <-> `<install-dir>/share/doc/llvm/LLVM.docx`
+
+Other projects
+ `<project>/docs/index.rst` <-> `<build-dir>/tools/<project>/docs/docx/<project>.docx` <-> `<install-dir>/share/doc/<project>/<project>.docx`
Index: openmp/docs/CMakeLists.txt
===================================================================
--- openmp/docs/CMakeLists.txt
+++ openmp/docs/CMakeLists.txt
@@ -99,5 +99,8 @@
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man openmp)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx openmp)
+ endif()
endif()
endif()
Index: llvm/docs/make.bat
===================================================================
--- llvm/docs/make.bat
+++ llvm/docs/make.bat
@@ -31,6 +31,7 @@
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
+ echo. docx to make DOCX files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. linkcheck to check all external links for integrity
@@ -153,6 +154,14 @@
goto end
)
+if "%1" == "docx" (
+ %SPHINXBUILD% -b docx %ALLSPHINXOPTS% %BUILDDIR%/docx
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The DOCX files are in %BUILDDIR%/docx.
+ goto end
+)
+
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
Index: llvm/docs/conf.py
===================================================================
--- llvm/docs/conf.py
+++ llvm/docs/conf.py
@@ -28,6 +28,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: llvm/docs/README.txt
===================================================================
--- llvm/docs/README.txt
+++ llvm/docs/README.txt
@@ -14,10 +14,15 @@
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
make -j3 docs-llvm-html
- $BROWSER <build-dir>/docs//html/index.html
+ $BROWSER <build-dir>/docs/html/index.html
-The mapping between reStructuredText files and generated documentation is
-`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `https://llvm.org/docs/Foo.html`.
+The correspondence between reStructuredText files and generated HTML pages is:
+
+LLVM project
+ `llvm/docs/Foo.rst` <-> `<build-dir>/docs/html/Foo.html` <-> `<install-dir>/share/doc/llvm/html/Foo.html` <-> `https://llvm.org/docs/Foo.html`
+
+Other projects
+ `<project>/docs/Foo.rst` <-> `<build-dir>/tools/<project>/docs/html/Foo.html` <-> `<install-dir>/share/doc/<project>/html/Foo.html`<-> `https://<project>.llvm.org/docs/Foo.html`
If you are interested in writing new documentation, you will want to read
`SphinxQuickstartTemplate.rst` which will get you writing documentation
@@ -25,7 +30,7 @@
markup syntax.
Manpage Output
-===============
+==============
Building the manpages is similar to building the HTML documentation. The
primary difference is to use the `man` makefile target, instead of the
@@ -35,13 +40,44 @@
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
make -j3 docs-llvm-man
- man -l >build-dir>/docs/man/FileCheck.1
+ man -l <build-dir>/docs/man/FileCheck.1
+
+The correspondence between reStructuredText files and generated man pages is:
+
+LLVM project
+ `llvm/docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
+
+Other projects
+ `<project>/docs/CommandGuide/Foo.rst` <-> `<build-dir>/tools/<project>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
-The correspondence between .rst files and man pages is
-`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
These .rst files are also included during HTML generation so they are also
-viewable online (as noted above) at e.g.
-`https://llvm.org/docs/CommandGuide/Foo.html`.
+viewable online:
+
+LLVM project
+ `https://llvm.org/docs/CommandGuide/Foo.html`
+
+Other projects
+ `https://<project>.llvm.org/docs/CommandGuide/Foo.html`
+
+DOCX Output
+===========
+
+Building the DOCX files is similar to building the HTML documentation. The
+primary difference is to use the `docx` makefile target, instead of the
+default (which is `html`). Sphinx then produces the DOCX files in the
+directory `<build-dir>/docs/docx/`.
+
+ cd <build-dir>
+ cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_DOCX=true <src-dir>
+ make -j3 docs-llvm-docx
+
+The correspondence between reStructuredText files and generated DOCX files is:
+
+LLVM project
+ `llvm/docs/index.rst` <-> `<build-dir>/docs/docx/LLVM.docx` <-> `<install-dir>/share/doc/llvm/LLVM.docx`
+
+Other projects
+ `<project>/docs/index.rst` <-> `<build-dir>/tools/<project>/docs/docx/<project>.docx` <-> `<install-dir>/share/doc/<project>/<project>.docx`
Checking links
==============
@@ -53,7 +89,7 @@
make -f Makefile.sphinx linkcheck
Doxygen page Output
-==============
+===================
Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.
Index: llvm/docs/Makefile.sphinx
===================================================================
--- llvm/docs/Makefile.sphinx
+++ llvm/docs/Makefile.sphinx
@@ -14,7 +14,7 @@
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext docx
all: html
@@ -34,6 +34,7 @@
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
+ @echo " docx to make DOCX files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@@ -127,6 +128,11 @@
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
+docx:
+ $(SPHINXBUILD) -b docx $(ALLSPHINXOPTS) $(BUILDDIR)/docx
+ @echo
+ @echo "Build finished. The DOCX files are in $(BUILDDIR)/docx."
+
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
Index: llvm/docs/CMakeLists.txt
===================================================================
--- llvm/docs/CMakeLists.txt
+++ llvm/docs/CMakeLists.txt
@@ -109,13 +109,16 @@
add_sphinx_target(html llvm)
endif()
-
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man llvm)
add_sphinx_target(man llvm-dwarfdump)
add_sphinx_target(man dsymutil)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx llvm)
+ endif()
+
endif()
endif()
@@ -159,9 +162,9 @@
add_dependencies(ocaml_doc ${doc_targets})
if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
- # ./ suffix is needed to copy the contents of html directory without
+ # / suffix is needed to copy the contents of html directory without
# appending html/ into LLVM_INSTALL_OCAMLDOC_HTML_DIR.
- install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html/.
+ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html/
COMPONENT ocamldoc-html
DESTINATION "${LLVM_INSTALL_OCAMLDOC_HTML_DIR}")
endif()
Index: llvm/docs/CMake.rst
===================================================================
--- llvm/docs/CMake.rst
+++ llvm/docs/CMake.rst
@@ -482,8 +482,8 @@
**LLVM_ENABLE_SPHINX**:BOOL
If specified, CMake will search for the ``sphinx-build`` executable and will make
- the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
- Defaults to OFF.
+ the ``SPHINX_OUTPUT_HTML``, ``SPHINX_OUTPUT_MAN`` and ``SPHINX_OUTPUT_DOCX`` CMake options
+ available. Defaults to OFF.
**LLVM_ENABLE_THREADS**:BOOL
Build with threads support, if available. Defaults to ON.
@@ -507,8 +507,8 @@
Defaults to ON.
**LLVM_EXPERIMENTAL_TARGETS_TO_BUILD**:STRING
- Semicolon-separated list of experimental targets to build and linked into
- llvm. This will build the experimental target without needing it to add to the
+ Semicolon-separated list of experimental targets to build and linked into
+ llvm. This will build the experimental target without needing it to add to the
list of all the targets available in the LLVM's main CMakeLists.txt.
**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
@@ -570,6 +570,11 @@
either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
`share/doc/llvm/html`.
+**LLVM_INSTALL_SPHINX_DOCX_DIR**:STRING
+ The path to install Sphinx-generated DOCX documentation to. This path can
+ either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
+ `share/doc/llvm`.
+
**LLVM_INSTALL_UTILS**:BOOL
If enabled, utility binaries like ``FileCheck`` and ``not`` will be installed
to CMAKE_INSTALL_PREFIX.
@@ -586,7 +591,7 @@
$ D:\git> git clone https://github.com/mjansson/rpmalloc
$ D:\llvm-project> cmake ... -DLLVM_INTEGRATED_CRT_ALLOC=D:\git\rpmalloc
-
+
This flag needs to be used along with the static CRT, ie. if building the
Release target, add -DLLVM_USE_CRT_RELEASE=MT.
@@ -719,6 +724,13 @@
is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
to ON.
+**SPHINX_OUTPUT_DOCX**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
+ the DOCX files are added (but not built by default unless ``LLVM_BUILD_DOCS``
+ is enabled). Requires that the Sphinx DOCX builder is installed using ``pip
+ install docxbuilder``. Currently the only target added is ``docs-llvm-docx``.
+ Defaults to OFF.
+
**SPHINX_WARNINGS_AS_ERRORS**:BOOL
If enabled then sphinx documentation warnings will be treated as
errors. Defaults to ON.
Index: llvm/cmake/modules/FindSphinx.cmake
===================================================================
--- llvm/cmake/modules/FindSphinx.cmake
+++ llvm/cmake/modules/FindSphinx.cmake
@@ -23,5 +23,6 @@
# Provide options for controlling different types of output
option(SPHINX_OUTPUT_HTML "Output standalone HTML files" ON)
option(SPHINX_OUTPUT_MAN "Output man pages" ON)
+option(SPHINX_OUTPUT_DOCX "Output DOCX files" OFF)
option(SPHINX_WARNINGS_AS_ERRORS "When building documentation treat warnings as errors" ON)
Index: llvm/cmake/modules/AddSphinxTarget.cmake
===================================================================
--- llvm/cmake/modules/AddSphinxTarget.cmake
+++ llvm/cmake/modules/AddSphinxTarget.cmake
@@ -81,7 +81,7 @@
if(NOT LLVM_ENABLE_IDE)
add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
- DEPENDS ${SPHINX_TARGET_NAME}
+ DEPENDS "${SPHINX_TARGET_NAME}"
COMPONENT "${project}-sphinx-man")
endif()
elseif (builder STREQUAL html)
@@ -89,18 +89,29 @@
set(${project_upper}_INSTALL_SPHINX_HTML_DIR "${CMAKE_INSTALL_DATADIR}/doc/${project}/html"
CACHE STRING "HTML documentation install directory for ${project}")
- # '/.' indicates: copy the contents of the directory directly into
- # the specified destination, without recreating the last component
- # of ${SPHINX_BUILD_DIR} implicitly.
- install(DIRECTORY "${SPHINX_BUILD_DIR}/."
+ install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
COMPONENT "${project}-sphinx-html"
- DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
+ DESTINATION "$CACHE{${project_upper}_INSTALL_SPHINX_HTML_DIR}")
if(NOT LLVM_ENABLE_IDE)
add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
DEPENDS ${SPHINX_TARGET_NAME}
COMPONENT "${project}-sphinx-html")
endif()
+ elseif (builder STREQUAL docx)
+ string(TOUPPER "${project}" project_upper)
+ set(${project_upper}_INSTALL_SPHINX_DOCX_DIR "${CMAKE_INSTALL_DATADIR}/doc/${project}"
+ CACHE STRING "DOCX documentation install directory for ${project}")
+
+ install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
+ COMPONENT "${project}-sphinx-docx"
+ DESTINATION "$CACHE{${project_upper}_INSTALL_SPHINX_DOCX_DIR}")
+
+ if(NOT LLVM_ENABLE_IDE)
+ add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
+ DEPENDS "${SPHINX_TARGET_NAME}"
+ COMPONENT "${project}-sphinx-docx")
+ endif()
else()
message(WARNING Installation of ${builder} not supported)
endif()
Index: lldb/docs/resources/build.rst
===================================================================
--- lldb/docs/resources/build.rst
+++ lldb/docs/resources/build.rst
@@ -393,6 +393,7 @@
> sudo apt-get install doxygen graphviz python3-sphinx
> sudo pip install epydoc
+ > sudo pip install docxbuilder
To build the documentation, configure with ``LLVM_ENABLE_SPHINX=ON`` and build the desired target(s).
@@ -400,6 +401,7 @@
> ninja docs-lldb-html
> ninja docs-lldb-man
+ > ninja docs-lldb-docx
> ninja lldb-cpp-doc
> ninja lldb-python-doc
Index: lldb/docs/conf.py
===================================================================
--- lldb/docs/conf.py
+++ lldb/docs/conf.py
@@ -44,6 +44,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
autodoc_default_options = {
'special-members': '__int__, __len__, __hex__, __oct__, __iter__',
}
Index: lldb/docs/CMakeLists.txt
===================================================================
--- lldb/docs/CMakeLists.txt
+++ lldb/docs/CMakeLists.txt
@@ -50,4 +50,9 @@
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man lldb)
endif()
+
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx lldb)
+ endif()
+
endif()
Index: lld/docs/sphinx_intro.rst
===================================================================
--- lld/docs/sphinx_intro.rst
+++ lld/docs/sphinx_intro.rst
@@ -41,7 +41,8 @@
Linux
Use your distribution's standard package management tool to install it,
- i.e., ``apt-get install easy_install`` or ``yum install easy_install``.
+ i.e., ``apt-get install easy_install``, ``yum install easy_install`` or
+ ``pip install``.
macOS
All modern macOS systems come with ``easy_install`` as part of the base
@@ -51,11 +52,13 @@
See the `setuptools <http://pypi.python.org/pypi/setuptools>`_ package web
page for instructions.
+If building DOCX documentation, then the Sphinx DOCX builder must be installed
+using ``pip install docxbuilder``.
.. _building_the_documentation:
Building the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to build the documentation need to add ``-DLLVM_ENABLE_SPHINX=ON`` to
your ``cmake`` command. Once you do this you can build the docs using
Index: lld/docs/make.bat
===================================================================
--- lld/docs/make.bat
+++ lld/docs/make.bat
@@ -31,6 +31,7 @@
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
+ echo. docx to make DOCX files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. linkcheck to check all external links for integrity
@@ -153,6 +154,14 @@
goto end
)
+if "%1" == "docx" (
+ %SPHINXBUILD% -b docx %ALLSPHINXOPTS% %BUILDDIR%/docx
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The DOCX files are in %BUILDDIR%/docx.
+ goto end
+)
+
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
Index: lld/docs/conf.py
===================================================================
--- lld/docs/conf.py
+++ lld/docs/conf.py
@@ -27,6 +27,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: lld/docs/CMakeLists.txt
===================================================================
--- lld/docs/CMakeLists.txt
+++ lld/docs/CMakeLists.txt
@@ -4,5 +4,8 @@
if (${SPHINX_OUTPUT_HTML})
add_sphinx_target(html lld)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx lld)
+ endif()
endif()
endif()
Index: libunwind/docs/conf.py
===================================================================
--- libunwind/docs/conf.py
+++ libunwind/docs/conf.py
@@ -27,6 +27,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: libunwind/docs/CMakeLists.txt
===================================================================
--- libunwind/docs/CMakeLists.txt
+++ libunwind/docs/CMakeLists.txt
@@ -4,4 +4,7 @@
if (${SPHINX_OUTPUT_HTML})
add_sphinx_target(html libunwind)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx libunwind)
+ endif()
endif()
Index: libcxx/docs/conf.py
===================================================================
--- libcxx/docs/conf.py
+++ libcxx/docs/conf.py
@@ -27,6 +27,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: libcxx/docs/Makefile.sphinx
===================================================================
--- libcxx/docs/Makefile.sphinx
+++ libcxx/docs/Makefile.sphinx
@@ -17,7 +17,7 @@
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext default
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man docx changes linkcheck doctest gettext default
default: html
Index: libcxx/docs/CMakeLists.txt
===================================================================
--- libcxx/docs/CMakeLists.txt
+++ libcxx/docs/CMakeLists.txt
@@ -5,5 +5,8 @@
if (${SPHINX_OUTPUT_HTML})
add_sphinx_target(html libcxx)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx libcxx)
+ endif()
endif()
endif()
Index: flang/docs/conf.py
===================================================================
--- flang/docs/conf.py
+++ flang/docs/conf.py
@@ -33,6 +33,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: flang/docs/CMakeLists.txt
===================================================================
--- flang/docs/CMakeLists.txt
+++ flang/docs/CMakeLists.txt
@@ -100,6 +100,9 @@
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man flang)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx flang)
+ endif()
endif()
endif()
Index: clang/docs/make.bat
===================================================================
--- clang/docs/make.bat
+++ clang/docs/make.bat
@@ -31,6 +31,7 @@
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
+ echo. docx to make DOCX files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. linkcheck to check all external links for integrity
@@ -153,6 +154,14 @@
goto end
)
+if "%1" == "docx" (
+ %SPHINXBUILD% -b docx %ALLSPHINXOPTS% %BUILDDIR%/docx
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The DOCX files are in %BUILDDIR%/docx.
+ goto end
+)
+
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
Index: clang/docs/conf.py
===================================================================
--- clang/docs/conf.py
+++ clang/docs/conf.py
@@ -29,6 +29,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: clang/docs/analyzer/make.bat
===================================================================
--- clang/docs/analyzer/make.bat
+++ clang/docs/analyzer/make.bat
@@ -31,6 +31,7 @@
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
+ echo. docx to make DOCX files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. linkcheck to check all external links for integrity
@@ -153,6 +154,14 @@
goto end
)
+if "%1" == "docx" (
+ %SPHINXBUILD% -b docx %ALLSPHINXOPTS% %BUILDDIR%/docx
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The DOCX files are in %BUILDDIR%/docx.
+ goto end
+)
+
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
Index: clang/docs/analyzer/conf.py
===================================================================
--- clang/docs/analyzer/conf.py
+++ clang/docs/analyzer/conf.py
@@ -28,6 +28,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: clang/docs/Makefile.sphinx
===================================================================
--- clang/docs/Makefile.sphinx
+++ clang/docs/Makefile.sphinx
@@ -34,6 +34,7 @@
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
+ @echo " docx to make DOCX files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@@ -135,6 +136,11 @@
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
+docx:
+ $(SPHINXBUILD) -b docx $(ALLSPHINXOPTS) $(BUILDDIR)/docx
+ @echo
+ @echo "Build finished. The DOCX files are in $(BUILDDIR)/docx."
+
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
Index: clang/docs/CMakeLists.txt
===================================================================
--- clang/docs/CMakeLists.txt
+++ clang/docs/CMakeLists.txt
@@ -103,19 +103,26 @@
if (LLVM_ENABLE_SPHINX)
include(AddSphinxTarget)
if (SPHINX_FOUND)
+
+ # Copy rst files to build directory before generating the
+ # documentation. Some of the rst files are generated, so they
+ # only exist in the build directory. Sphinx needs all files in
+ # the same directory in order to generate the files, so we need to
+ # copy all the non-generated rst files from the source to the build
+ # directory before we run Sphinx.
+ add_custom_target(copy-clang-rst-docs
+ COMMAND "${CMAKE_COMMAND}" -E copy_directory
+ "${CMAKE_CURRENT_SOURCE_DIR}"
+ "${CMAKE_CURRENT_BINARY_DIR}")
+
+ # Generated files
+ gen_rst_file_from_td(AttributeReference.rst -gen-attr-docs ../include/clang/Basic/Attr.td copy-clang-rst-docs)
+ gen_rst_file_from_td(DiagnosticsReference.rst -gen-diag-docs ../include/clang/Basic/Diagnostic.td copy-clang-rst-docs)
+ gen_rst_file_from_td(ClangCommandLineReference.rst -gen-opt-docs ../include/clang/Driver/ClangOptionDocs.td copy-clang-rst-docs)
+
if (${SPHINX_OUTPUT_HTML})
add_sphinx_target(html clang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}")
- # Copy rst files to build directory before generating the html
- # documentation. Some of the rst files are generated, so they
- # only exist in the build directory. Sphinx needs all files in
- # the same directory in order to generate the html, so we need to
- # copy all the non-gnerated rst files from the source to the build
- # directory before we run sphinx.
- add_custom_target(copy-clang-rst-docs
- COMMAND "${CMAKE_COMMAND}" -E copy_directory
- "${CMAKE_CURRENT_SOURCE_DIR}"
- "${CMAKE_CURRENT_BINARY_DIR}")
add_dependencies(docs-clang-html copy-clang-rst-docs)
add_custom_command(TARGET docs-clang-html POST_BUILD
@@ -123,13 +130,17 @@
"${CMAKE_CURRENT_SOURCE_DIR}/LibASTMatchersReference.html"
"${CMAKE_CURRENT_BINARY_DIR}/html/LibASTMatchersReference.html")
- # Generated files
- gen_rst_file_from_td(AttributeReference.rst -gen-attr-docs ../include/clang/Basic/Attr.td docs-clang-html)
- gen_rst_file_from_td(DiagnosticsReference.rst -gen-diag-docs ../include/clang/Basic/Diagnostic.td docs-clang-html)
- gen_rst_file_from_td(ClangCommandLineReference.rst -gen-opt-docs ../include/clang/Driver/ClangOptionDocs.td docs-clang-html)
endif()
+
if (${SPHINX_OUTPUT_MAN})
- add_sphinx_target(man clang)
+ add_sphinx_target(man clang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}")
+ add_dependencies(docs-clang-man copy-clang-rst-docs)
endif()
+
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx clang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}")
+ add_dependencies(docs-clang-docx copy-clang-rst-docs)
+ endif()
+
endif()
endif()
Index: clang-tools-extra/docs/make.bat
===================================================================
--- clang-tools-extra/docs/make.bat
+++ clang-tools-extra/docs/make.bat
@@ -31,6 +31,7 @@
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
+ echo. docx to make DOCX files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. linkcheck to check all external links for integrity
@@ -153,6 +154,14 @@
goto end
)
+if "%1" == "docx" (
+ %SPHINXBUILD% -b docx %ALLSPHINXOPTS% %BUILDDIR%/docx
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The DOCX files are in %BUILDDIR%/docx.
+ goto end
+)
+
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
Index: clang-tools-extra/docs/conf.py
===================================================================
--- clang-tools-extra/docs/conf.py
+++ clang-tools-extra/docs/conf.py
@@ -28,6 +28,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax']
+if tags.has('builder-docx'):
+ extensions.append('docxbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Index: clang-tools-extra/docs/CMakeLists.txt
===================================================================
--- clang-tools-extra/docs/CMakeLists.txt
+++ clang-tools-extra/docs/CMakeLists.txt
@@ -98,5 +98,8 @@
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man clang-tools)
endif()
+ if (${SPHINX_OUTPUT_DOCX})
+ add_sphinx_target(docx clang-tools)
+ endif()
endif()
endif()
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
