From 15acaad79d6e79fae769db03dcc9c725777b774b Mon Sep 17 00:00:00 2001 From: =?utf8?q?Christian=20K=C3=BChnel?= Date: Wed, 4 Aug 2021 14:26:37 +0000 Subject: [PATCH] [doc] added section on generating the html doc Added a new section on generating the html documentation from the rst/md sources to our documentation. Background: I wanted to check what my documenation changes would look like on the website and had a hard time finding how to do that. So I wanted to save other folks the effort. Differential Revision: https://reviews.llvm.org/D107460 --- llvm/docs/MarkdownQuickstartTemplate.md | 4 ++++ llvm/docs/SphinxQuickstartTemplate.rst | 29 +++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/llvm/docs/MarkdownQuickstartTemplate.md b/llvm/docs/MarkdownQuickstartTemplate.md index 1ed9f2f..8d6434a 100644 --- a/llvm/docs/MarkdownQuickstartTemplate.md +++ b/llvm/docs/MarkdownQuickstartTemplate.md @@ -155,3 +155,7 @@ integration documentation can be found in the [recommonmark docs]. [Common Mark spec]: http://spec.commonmark.org/0.28/ [recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html + +## Generating the documentation + +see [Sphinx Quickstart Template](SphinxQuickstartTemplate.html#generating-the-documentation) diff --git a/llvm/docs/SphinxQuickstartTemplate.rst b/llvm/docs/SphinxQuickstartTemplate.rst index 5ebb92a..dcf2164 100644 --- a/llvm/docs/SphinxQuickstartTemplate.rst +++ b/llvm/docs/SphinxQuickstartTemplate.rst @@ -165,3 +165,32 @@ without any syntax highlighting like this: ... +Generating the documentation +============================ + +You can generate the HTML documentation from the sources locally if you want to +see what they would look like. In addition to the normal +`build tools `_ +you need to install `Sphinx`_ and the +`recommonmark `_ extension. + +On Debian you can install these with: + +.. code-block:: console + + sudo apt install -y sphinx-doc python-recommonmark-doc + +Then run cmake to build the documentation inside the ``llvm-project`` checkout: + +.. code-block:: console + + mkdir build + cd build + cmake -DLLVM_ENABLE_SPHINX=On ../llvm + cmake --build . --target docs-llvm-html + +In case you already have the Cmake build set up and want to reuse that, +just set the CMake variable ``LLVM_ENABLE_SPHINX=On``. + +After that you find the generated documentation in ``build/docs/html`` +folder. -- 2.7.4