[llvm-commits] [PATCH][CMake][docs] Add docs-sphinx target to build the Sphinx docs.

[Chandler Carruth]

Comments inline:

--- /dev/null
+++ b/docs/CMakeLists.txt
@@ -0,0 +1,28 @@
+find_package(Sphinx)
+
+if( ${SPHINX_FOUND} )
+  set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build")

This appears to be unused.

+  set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")

The Makefiles use 'doctrees' w/o the _ prefix.

+  set(SPHINX_HTML_DIR "${LLVM_BINARY_DIR}/docs/html")
+
+  file(GLOB_RECURSE REST_SOURCES "*.rst")
+  file(GLOB HTML_SOURCES "*.html" "tutorial/*.html")

I think the problems with GLOBs in CMake hold just as true for
documentation as they do for source code...

+  source_group(ReST FILES ${REST_SOURCES})
+  source_group(HTML FILES ${HTML_SOURCES})
+
+  add_custom_target(docs-sphinx

Can you use add_custom_command so that these aren't re-generated on every
build? Maybe there is a log file of the run you can list as the output?

+    ${SPHINX_EXECUTABLE}
+    -q
+    -b html
+    -d "${SPHINX_CACHE_DIR}"

Why hoist this into a variable rather than just writing it out here?

+    "${CMAKE_CURRENT_SOURCE_DIR}"
+    "${SPHINX_HTML_DIR}"

The Makefiles put the built docs in 'docs/_build/html' AFAICT, not
'docs/html'.

+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"

If you set the source dir above, can you not mess with the working dir? (I
much rather the working directory *not* be the source tree)

+    COMMENT "Building HTML documentation with Sphinx"
+    SOURCES ${REST_SOURCES} ${HTML_SOURCES} conf.py
+    )
+
+  install(DIRECTORY "${SPHINX_HTML_DIR}/"
+          DESTINATION docs/llvm/html
+          )

I don't see *any* installation support for sphinx in LLVM currently; this
seems definitely wrong.


On Tue, Jun 26, 2012 at 4:48 PM, Michael Spencer <bigcheesegs at gmail.com>wrote:

> This patch adds a docs-sphinx target which builds the Sphinx docs and
> adds an install rule. I believe they get installed to the same
> location as the autoconf build ($(prefix)/docs/llvm/html).
>
> The next step is to configure the conf.py file instead of hard coding
> the version number, but this would break the website, so  I need to
> know how that should be handled.
>
> - Michael Spencer
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120626/310b9037/attachment.html>