diff --git a/clang-tools-extra/docs/CMakeLists.txt b/clang-tools-extra/docs/CMakeLists.txt --- a/clang-tools-extra/docs/CMakeLists.txt +++ b/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() diff --git a/clang-tools-extra/docs/conf.py b/clang-tools-extra/docs/conf.py --- a/clang-tools-extra/docs/conf.py +++ b/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'] diff --git a/clang-tools-extra/docs/make.bat b/clang-tools-extra/docs/make.bat --- a/clang-tools-extra/docs/make.bat +++ b/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 diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt --- a/clang/docs/CMakeLists.txt +++ b/clang/docs/CMakeLists.txt @@ -137,5 +137,10 @@ 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() diff --git a/clang/docs/Makefile.sphinx b/clang/docs/Makefile.sphinx --- a/clang/docs/Makefile.sphinx +++ b/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..." diff --git a/clang/docs/analyzer/conf.py b/clang/docs/analyzer/conf.py --- a/clang/docs/analyzer/conf.py +++ b/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'] diff --git a/clang/docs/analyzer/make.bat b/clang/docs/analyzer/make.bat --- a/clang/docs/analyzer/make.bat +++ b/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 diff --git a/clang/docs/conf.py b/clang/docs/conf.py --- a/clang/docs/conf.py +++ b/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'] diff --git a/clang/docs/make.bat b/clang/docs/make.bat --- a/clang/docs/make.bat +++ b/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 diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt --- a/flang/docs/CMakeLists.txt +++ b/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() diff --git a/flang/docs/conf.py b/flang/docs/conf.py --- a/flang/docs/conf.py +++ b/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'] diff --git a/libcxx/docs/CMakeLists.txt b/libcxx/docs/CMakeLists.txt --- a/libcxx/docs/CMakeLists.txt +++ b/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() diff --git a/libcxx/docs/Makefile.sphinx b/libcxx/docs/Makefile.sphinx --- a/libcxx/docs/Makefile.sphinx +++ b/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 diff --git a/libcxx/docs/conf.py b/libcxx/docs/conf.py --- a/libcxx/docs/conf.py +++ b/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'] diff --git a/libunwind/docs/CMakeLists.txt b/libunwind/docs/CMakeLists.txt --- a/libunwind/docs/CMakeLists.txt +++ b/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() diff --git a/libunwind/docs/conf.py b/libunwind/docs/conf.py --- a/libunwind/docs/conf.py +++ b/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'] diff --git a/lld/docs/CMakeLists.txt b/lld/docs/CMakeLists.txt --- a/lld/docs/CMakeLists.txt +++ b/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() diff --git a/lld/docs/conf.py b/lld/docs/conf.py --- a/lld/docs/conf.py +++ b/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'] diff --git a/lld/docs/make.bat b/lld/docs/make.bat --- a/lld/docs/make.bat +++ b/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 diff --git a/lld/docs/sphinx_intro.rst b/lld/docs/sphinx_intro.rst --- a/lld/docs/sphinx_intro.rst +++ b/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 `_ 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 diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt --- a/lldb/docs/CMakeLists.txt +++ b/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() diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py --- a/lldb/docs/conf.py +++ b/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__', } diff --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst --- a/lldb/docs/resources/build.rst +++ b/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 diff --git a/llvm/cmake/modules/AddSphinxTarget.cmake b/llvm/cmake/modules/AddSphinxTarget.cmake --- a/llvm/cmake/modules/AddSphinxTarget.cmake +++ b/llvm/cmake/modules/AddSphinxTarget.cmake @@ -84,7 +84,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) @@ -92,18 +92,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() diff --git a/llvm/cmake/modules/FindSphinx.cmake b/llvm/cmake/modules/FindSphinx.cmake --- a/llvm/cmake/modules/FindSphinx.cmake +++ b/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) diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst --- a/llvm/docs/CMake.rst +++ b/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. diff --git a/llvm/docs/CMakeLists.txt b/llvm/docs/CMakeLists.txt --- a/llvm/docs/CMakeLists.txt +++ b/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() diff --git a/llvm/docs/Makefile.sphinx b/llvm/docs/Makefile.sphinx --- a/llvm/docs/Makefile.sphinx +++ b/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..." diff --git a/llvm/docs/README.txt b/llvm/docs/README.txt --- a/llvm/docs/README.txt +++ b/llvm/docs/README.txt @@ -14,10 +14,15 @@ cd cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true make -j3 docs-llvm-html - $BROWSER /docs//html/index.html + $BROWSER /docs/html/index.html -The mapping between reStructuredText files and generated documentation is -`docs/Foo.rst` <-> `/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` <-> `/docs/html/Foo.html` <-> `/share/doc/llvm/html/Foo.html` <-> `https://llvm.org/docs/Foo.html` + +Other projects + `/docs/Foo.rst` <-> `/tools//docs/html/Foo.html` <-> `/share/doc//html/Foo.html`<-> `https://.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 cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true make -j3 docs-llvm-man - man -l >build-dir>/docs/man/FileCheck.1 + man -l /docs/man/FileCheck.1 + +The correspondence between reStructuredText files and generated man pages is: + +LLVM project + `llvm/docs/CommandGuide/Foo.rst` <-> `/docs/man/Foo.1` <-> `/share/man/man1/Foo.1` + +Other projects + `/docs/CommandGuide/Foo.rst` <-> `/tools//docs/man/Foo.1` <-> `/share/man/man1/Foo.1` -The correspondence between .rst files and man pages is -`docs/CommandGuide/Foo.rst` <-> `/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://.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 `/docs/docx/`. + + cd + cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_DOCX=true + make -j3 docs-llvm-docx + +The correspondence between reStructuredText files and generated DOCX files is: + +LLVM project + `llvm/docs/index.rst` <-> `/docs/docx/LLVM.docx` <-> `/share/doc/llvm/LLVM.docx` + +Other projects + `/docs/index.rst` <-> `/tools//docs/docx/.docx` <-> `/share/doc//.docx` Checking links ============== @@ -53,7 +89,7 @@ make -f Makefile.sphinx linkcheck Doxygen page Output -============== +=================== Install doxygen and dot2tex . diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py --- a/llvm/docs/conf.py +++ b/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'] diff --git a/llvm/docs/make.bat b/llvm/docs/make.bat --- a/llvm/docs/make.bat +++ b/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 diff --git a/openmp/docs/CMakeLists.txt b/openmp/docs/CMakeLists.txt --- a/openmp/docs/CMakeLists.txt +++ b/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() diff --git a/openmp/docs/README.txt b/openmp/docs/README.txt --- a/openmp/docs/README.txt +++ b/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 cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true make - $BROWSER /projects/openmp/docs//html/index.html + $BROWSER /projects/openmp/docs/html/index.html -The mapping between reStructuredText files and generated documentation is -`docs/Foo.rst` <-> `/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` <-> `/docs/html/Foo.html` <-> `/share/doc/llvm/html/Foo.html` <-> `https://llvm.org/docs/Foo.html` + +Other projects + `/docs/Foo.rst` <-> `/tools//docs/html/Foo.html` <-> `/share/doc//html/Foo.html`<-> `https://.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 cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true make - man -l >build-dir>/docs/man/FileCheck.1 + man -l /docs/man/FileCheck.1 + +The correspondence between reStructuredText files and generated man pages is: + +LLVM project + `llvm/docs/CommandGuide/Foo.rst` <-> `/docs/man/Foo.1` <-> `/share/man/man1/Foo.1` + +Other projects + `/docs/CommandGuide/Foo.rst` <-> `/tools//docs/man/Foo.1` <-> `/share/man/man1/Foo.1` -The correspondence between .rst files and man pages is -`docs/CommandGuide/Foo.rst` <-> `/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://.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 `/docs/docx/`. + + cd + cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_DOCX=true + make + +The correspondence between reStructuredText files and generated DOCX files is: + +LLVM project + `llvm/docs/index.rst` <-> `/docs/docx/LLVM.docx` <-> `/share/doc/llvm/LLVM.docx` + +Other projects + `/docs/index.rst` <-> `/tools//docs/docx/.docx` <-> `/share/doc//.docx` diff --git a/openmp/docs/conf.py b/openmp/docs/conf.py --- a/openmp/docs/conf.py +++ b/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'] diff --git a/polly/docs/CMakeLists.txt b/polly/docs/CMakeLists.txt --- a/polly/docs/CMakeLists.txt +++ b/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() diff --git a/polly/docs/conf.py b/polly/docs/conf.py --- a/polly/docs/conf.py +++ b/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']