From 34ea1f1520a290fbe19d0f9fbe413f50157120a9 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 4 Feb 2014 10:09:40 -0500 Subject: Utilities/Sphinx: Add option to build 'text' format Add SPHINX_TEXT to enable the Sphinx 'text' builder. Mark it as advanced and do not add install rules. This is intended for use by the release manager to build the release notes in text format suitable for email. --- Utilities/Sphinx/CMakeLists.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index c60788f..23dc6ae 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/Utilities/Sphinx/CMakeLists.txt @@ -24,12 +24,15 @@ project(CMakeHelp NONE) option(SPHINX_MAN "Build man pages with Sphinx" OFF) option(SPHINX_HTML "Build html help with Sphinx" OFF) +option(SPHINX_TEXT "Build text help with Sphinx (not installed)" OFF) find_program(SPHINX_EXECUTABLE NAMES sphinx-build DOC "Sphinx Documentation Builder (sphinx-doc.org)" ) -if(NOT SPHINX_MAN AND NOT SPHINX_HTML) +mark_as_advanced(SPHINX_TEXT) + +if(NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_TEXT) return() elseif(NOT SPHINX_EXECUTABLE) message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!") @@ -57,6 +60,9 @@ endif() if(SPHINX_MAN) list(APPEND doc_formats man) endif() +if(SPHINX_TEXT) + list(APPEND doc_formats text) +endif() set(doc_format_outputs "") set(doc_format_last "") -- cgit v0.12 From 70309e7083fa1428d429f4b1fba9441e8765588f Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 4 Feb 2014 10:13:35 -0500 Subject: Help: Add documents for release notes Add a release/index.rst document titled "CMake Release Notes" to hold the toctree for release notes. Add a "Release Notes" section to the top-level html document index to link to the new document. --- Help/index.rst | 10 ++++++++++ Help/release/index.rst | 8 ++++++++ 2 files changed, 18 insertions(+) create mode 100644 Help/release/index.rst diff --git a/Help/index.rst b/Help/index.rst index 7fce223..a4abfbf 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -39,6 +39,16 @@ Reference Manuals /manual/cmake-toolchains.7 /manual/cmake-variables.7 +.. only:: html or text + + Release Notes + ############# + + .. toctree:: + :maxdepth: 1 + + /release/index + .. only:: html Index and Search diff --git a/Help/release/index.rst b/Help/release/index.rst new file mode 100644 index 0000000..52fedc1 --- /dev/null +++ b/Help/release/index.rst @@ -0,0 +1,8 @@ +CMake Release Notes +******************* + +Releases +======== + +.. toctree:: + :maxdepth: 1 -- cgit v0.12 From ccc8704777a42a00dcb4a7d62fcbfa79702a8923 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 4 Feb 2014 10:28:12 -0500 Subject: Help: Add documents to collect notes between releases Add a release/dev.txt file and include it from release/index.rst in development versions. Add a "Changes Since Release" section with a toctree that globs adjacent "dev/*" documents. Add a sample topic document explaining how topic-specific release note documents work. This approach will allow developers to write release notes for their changes as they are made. The release manager may then consolidate and organize the notes for a specific release version. --- Help/release/dev.txt | 16 ++++++++++++++++ Help/release/dev/0-sample-topic.rst | 7 +++++++ Help/release/index.rst | 6 ++++++ 3 files changed, 29 insertions(+) create mode 100644 Help/release/dev.txt create mode 100644 Help/release/dev/0-sample-topic.rst diff --git a/Help/release/dev.txt b/Help/release/dev.txt new file mode 100644 index 0000000..2cf9193 --- /dev/null +++ b/Help/release/dev.txt @@ -0,0 +1,16 @@ +.. + This file should be included by the adjacent "index.rst" + in development versions but not in release versions. + +Changes Since Release +===================== + +The following noteworthy changes have been made in this development +version since the preceding release but have not yet been consolidated +into notes for a specific release version: + +.. toctree:: + :maxdepth: 1 + :glob: + + dev/* diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/index.rst b/Help/release/index.rst index 52fedc1..f8367d7 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -1,6 +1,12 @@ CMake Release Notes ******************* +.. + This file should include the adjacent "dev.txt" file + in development versions but not in release versions. + +.. include:: dev.txt + Releases ======== -- cgit v0.12