From b6189210d496902ca85c41d3d9924ed2bc668052 Mon Sep 17 00:00:00 2001 From: Rogier Date: Fri, 27 Nov 2015 08:46:18 +0100 Subject: [PATCH] Some more changes to the HTML generation procedure and its documentation. --- doc/CMakeLists.txt | 7 ++++++- doc/build-instructions.rst | 30 ++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index f0fe7cf..a0f204b 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -43,7 +43,12 @@ elseif(USE_RST2HTML EQUAL -1) message(STATUS "Conversion of documentation to html disabled (because python docutils not found)") endif (DOCUTILS_FOUND) elseif(USE_RST2HTML EQUAL 0) - message(STATUS "Conversion of documentation to html disabled (because disabled previously)") + if (DOCUTILS_FOUND) + set(USE_RST2HTML 1) + message(STATUS "Conversion of documentation to html enabled (because python docutils has become available)") + else (DOCUTILS_FOUND) + message(STATUS "Conversion of documentation to html disabled (because python docutils still not found)") + endif (DOCUTILS_FOUND) elseif(USE_RST2HTML EQUAL 1) message(STATUS "Conversion of documentation to html enabled (because enabled previously)") endif(REQUIRE_HTML_DOCUMENTATION) diff --git a/doc/build-instructions.rst b/doc/build-instructions.rst index 6fd5bea..9a06324 100644 --- a/doc/build-instructions.rst +++ b/doc/build-instructions.rst @@ -238,6 +238,8 @@ REQUIRE_HTML_DOCUMENTATION: By default, HTML documentation will be generated if python-docutils is found, else it will not be generated. + See also the note below. + DISABLE_HTML_DOCUMENTATION: Whether to skip generation of HTML documentation, even if python-docutils could be found. @@ -247,6 +249,34 @@ DISABLE_HTML_DOCUMENTATION: even if the converted documentation is available (e.g. because it was generated manually). + See also the note below. + +HTML Documentation note: + If both REQUIRE_HTML_DOCUMENTATION and DISABLE_HTML_DOCUMENTATION are disabled, + then the question of whether HTML documentation will be generated depends on + whether python-docutils is installed. If installed, then henceforth HTML + documentation will be generated. If not installed, then it will not be generated. + + As long as REQUIRE_HTML_DOCUMENTATION and DISABLE_HTML_DOCUMENTATION are both + disabled then, for consistency, once python-docutils has been found to be installed + and the decision has been made to generate HTML documentation, this decision persists. + If subsequently python-docutils is deinstalled, or can no longer be found, later + builds will fail, until the situation has been fixed. This can be done in several + ways: + + - (Obviously:) Reinstalling python-docutils, or making sure it can be found. + + - Enabling both REQUIRE_HTML_DOCUMENTATION and DISABLE_HTML_DOCUMENTATION. As this + is not a sensible combination, the build system will disable both, and it will + then also reevaluate the persistent decision to generate HTML documentation. + + - Setting DISABLE_HTML_DOCUMENTATION to True to permanently disable generation of + HTML documentation. + + - Setting DISABLE_HTML_DOCUMENTATION to True, running cmake, and then setting it + back to false. This will disable HTML generation until python-docutils is + available again. + Converting the Documentation ============================