From 2c42bae09f01c3ebb53850d49edc5c102309685b Mon Sep 17 00:00:00 2001 From: patrick96 Date: Fri, 14 Dec 2018 09:34:31 +0100 Subject: [PATCH] refactor(doc): Use cmake APP_VERSION in conf.py This also moves the doc generation completely into cmake (no more Makefile). To generate the docs the project needs to first be configured and then `make doc` can be run. The approach used is leaned on the cmake's project own use of Sphinx: Utilities/Sphinx/CMakeLists.txt --- .gitignore | 1 - doc/.gitignore | 1 - doc/CMakeLists.txt | 37 ++++++++++++++++++++++++++++++++----- doc/Makefile | 19 ------------------- doc/README.md | 10 +++++++--- doc/{conf.py => conf.py.in} | 7 +++---- 6 files changed, 42 insertions(+), 33 deletions(-) delete mode 100644 doc/.gitignore delete mode 100644 doc/Makefile rename doc/{conf.py => conf.py.in} (97%) diff --git a/.gitignore b/.gitignore index e69069a1..e19097e5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ /build/* /doc/config /include/settings.hpp -/man/polybar.1 /polybar /polybar-msg /tags diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index 378eac25..00000000 --- a/doc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -build diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index b43a3ade..aa2dd85e 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -94,16 +94,43 @@ install(FILES config # }}} # Documentation {{{ +configure_file(conf.py.in conf.py @ONLY) -add_custom_target(doc ALL - WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/doc - COMMAND make html man) +set(SPHINX_FLAGS "" CACHE STRING "Flags to pass to sphinx-build") +separate_arguments(sphinx_flags UNIX_COMMAND "${SPHINX_FLAGS}") -install(DIRECTORY build/html/ +set(doc_path "${CMAKE_CURRENT_SOURCE_DIR}") + +# We want to run `sphinx-build` with the following builders +set(doc_builders "html" "man") + +# Name of all documentation targets +set(doc_targets "") + +foreach(builder ${doc_builders}) + set(doc_target "doc_${builder}") + set(builder_log "builder-${builder}.log") + add_custom_target(${doc_target} + COMMAND sphinx-build + -b ${builder} + -c "${CMAKE_CURRENT_BINARY_DIR}" + -d "${CMAKE_CURRENT_BINARY_DIR}/doctrees" + ${sphinx_flags} + "${CMAKE_SOURCE_DIR}/doc" + "${CMAKE_CURRENT_BINARY_DIR}/${builder}" > ${builder_log} + COMMENT "sphinx-build ${builder}: see doc/${builder_log}") + + list(APPEND doc_targets ${doc_target}) +endforeach() + +# Dummy target that depends on all documentation targets +add_custom_target(doc ALL DEPENDS ${doc_targets}) + +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ DESTINATION share/doc/polybar COMPONENT doc) -install(FILES build/man/polybar.1 +install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/polybar.1 DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man1 COMPONENT doc) # }}} diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 5dede4aa..00000000 --- a/doc/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/README.md b/doc/README.md index b9aae425..f1dff97e 100644 --- a/doc/README.md +++ b/doc/README.md @@ -11,7 +11,11 @@ The documentation uses [Sphinx](http://www.sphinx-doc.org/en/stable/) with the " [`sphinx_rtd_theme`](https://github.com/rtfd/sphinx_rtd_theme/) to generate the documentation, so you will need to have those installed. -You can then run `make html` inside this folder and sphinx will generate the html documentation inside `doc/build/html`. -Open `doc/build/html/index.html` to read the documentation in the browser. +To generate the documentation you first need to configure polybar the same as when you compile it (`cmake ..` in `build` +folder). +After that you can run `make doc` to generate all of the documentation or `make doc_html` or `make doc_man` to only +generate the html documentation or the man pages. -With `make man` it will generate the man pages in the `doc/build/man` folder. +Open `build/doc/html/index.html` to read the documentation in the browser. + +The manual pages are placed in `build/doc/man`. diff --git a/doc/conf.py b/doc/conf.py.in similarity index 97% rename from doc/conf.py rename to doc/conf.py.in index 00b909ce..6046d371 100644 --- a/doc/conf.py +++ b/doc/conf.py.in @@ -24,8 +24,7 @@ copyright = '' author = 'Polybar Team' # The short X.Y version -# TODO set this dynamically -version = '3.2.1' +version = '@APP_VERSION@' # The full version, including alpha/beta/rc tags release = version @@ -43,7 +42,7 @@ extensions = [ ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['@doc_path@/_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -86,7 +85,7 @@ html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ['@doc_path@/_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names.