diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..378eac25 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +build diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 948f8f48..4f2f0527 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,3 +1,8 @@ +cmake_minimum_required(VERSION 3.1.0 FATAL_ERROR) + +# Only used if documentation is built on its own +project(polybar-doc NONE) + find_program(SPHINX_EXECUTABLE NAMES sphinx-build DOC "Sphinx Documentation Builder") @@ -6,14 +11,14 @@ if(NOT SPHINX_EXECUTABLE) message_colored(FATAL_ERROR "Failed to locate sphinx-build" 31) endif() -# Configures conf.py in the current folder and puts it in the build folder -configure_file(conf.py conf.py @ONLY) - set(SPHINX_FLAGS "" CACHE STRING "Flags to pass to sphinx-build") separate_arguments(sphinx_flags UNIX_COMMAND "${SPHINX_FLAGS}") set(doc_path "${CMAKE_CURRENT_SOURCE_DIR}") +# Configures conf.py in the current folder and puts it in the build folder +configure_file(conf.py conf.py @ONLY) + # We want to run `sphinx-build` with the following builders set(doc_builders "html" "man") @@ -26,10 +31,13 @@ foreach(builder ${doc_builders}) add_custom_target(${doc_target} COMMAND ${SPHINX_EXECUTABLE} -b ${builder} + # conf.py dir -c "${CMAKE_CURRENT_BINARY_DIR}" -d "${CMAKE_CURRENT_BINARY_DIR}/doctrees" ${sphinx_flags} - "${CMAKE_SOURCE_DIR}/doc" + # Documentation source file dir + "${CMAKE_CURRENT_SOURCE_DIR}" + # Output dir "${CMAKE_CURRENT_BINARY_DIR}/${builder}" > ${builder_log} COMMENT "sphinx-build ${builder}: see doc/${builder_log}") diff --git a/doc/README.md b/doc/README.md index 57e2ed54..38fd0b93 100644 --- a/doc/README.md +++ b/doc/README.md @@ -10,11 +10,13 @@ target `doc`). The documentation uses [Sphinx](http://www.sphinx-doc.org/en/stable/) to generate the documentation, so you will need to have that installed. -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. +If you build polybar normally while having Sphinx installed during configuration, the documentation will be enabled and +built as well. Building the documentation can be disabled by passing `-DBUILD_DOC=OFF` to `cmake`. -Open `build/doc/html/index.html` to read the documentation in the browser. +Alternatively the documentation can be built without the rest of polybar, for that run `cmake` only on the `doc` +directory. For example, create a `build` directory in `doc` and then run `cmake ..` in there. -The manual pages are placed in `build/doc/man`. +Once configured, all of the documentation can be generated with `make doc` or use `make doc_html` or `make doc_man` to +only generate the html documentation or the man pages respectively. + +The HTML documentation is in `doc/html/index.html` in your build directory and the man pages are in `doc/man`.