From c5988668edcb58b749ddcd57168dc0944bb750e2 Mon Sep 17 00:00:00 2001 From: msclock Date: Wed, 6 Mar 2024 00:50:40 +0800 Subject: [PATCH] docs: simplify docs build (#64) Signed-off-by: msclock --- .gitignore | 3 ++ CMakeLists.txt | 7 ----- cmake/ConfigureCoverage.cmake | 6 +--- cmake/ConfigureDocs.cmake | 25 ++++++++++------- docs/api.md | 4 +-- docs/cmake_workflow.md | 8 ++++-- docs/conf.py | 9 ++++-- docs/coverage.md | 5 ---- docs/index.md | 28 +++++++++++++++---- docs/requirements.txt | 9 +++--- src/compile/CMakeLists.txt | 9 +++--- template/.gitignore.jinja | 3 ++ template/CMakeLists.txt.jinja | 7 ----- .../api.md.jinja | 4 +-- .../cmake_workflow.md | 8 ++++-- .../conf.py.jinja | 9 ++++-- .../coverage.md | 5 ---- .../index.md.jinja | 28 +++++++++++++++---- .../requirements.txt | 9 +++--- template/cmake/ConfigureCoverage.cmake | 6 +--- template/cmake/ConfigureDocs.cmake.jinja | 25 ++++++++++------- .../CMakeLists.txt | 9 +++--- 22 files changed, 130 insertions(+), 96 deletions(-) delete mode 100644 docs/coverage.md delete mode 100644 template/[% if docs_type == 'sphinx' %]docs[% endif %]/coverage.md diff --git a/.gitignore b/.gitignore index b8eb88fb..d5782961 100644 --- a/.gitignore +++ b/.gitignore @@ -341,3 +341,6 @@ ASALocalRun/ # Ignore things from copier .copier-answers.yml + +# Documenation files +docs/_build diff --git a/CMakeLists.txt b/CMakeLists.txt index 0e5d2286..e145e1ac 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -39,8 +39,6 @@ find_package(cmake-modules REQUIRED) include(cmake-modules/configure/Default) include(cmake-modules/configure/Common) include(cmake-modules/configure/CheckBuildDir) -include(cmake-modules/configure/ConfigDoxygen) -include(cmake-modules/configure/FindSphinx) include(cmake-modules/configure/UniqueOutputBinaryDir) include(cmake-modules/build/Default) include(cmake-modules/build/Ccache) @@ -58,11 +56,6 @@ include(cmake-modules/install/Runpath) # Add _DEBUG macro add_debug_macro() -# LTO for release -if(${CMAKE_BUILD_TYPE} MATCHES [[Release]]) - link_time_optimization() -endif() - create_uninstall_target() # Project custom modules diff --git a/cmake/ConfigureCoverage.cmake b/cmake/ConfigureCoverage.cmake index 0ce01f28..13990b9a 100644 --- a/cmake/ConfigureCoverage.cmake +++ b/cmake/ConfigureCoverage.cmake @@ -6,9 +6,5 @@ add_code_coverage_all_targets( ${VCPKG_INSTALLED_DIR}/* ${CMAKE_BINARY_DIR}/* /usr/* - HTML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}_docs/coverage) + HTML_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/docs/_build/coverage) # cmake-format: on - -if(TARGET ${CMAKE_PROJECT_NAME}_docs) - add_dependencies(ccov-all ${CMAKE_PROJECT_NAME}_docs) -endif() diff --git a/cmake/ConfigureDocs.cmake b/cmake/ConfigureDocs.cmake index 44fa2cc2..308e56f1 100644 --- a/cmake/ConfigureDocs.cmake +++ b/cmake/ConfigureDocs.cmake @@ -6,29 +6,34 @@ configdoxygen() if(DOXYGEN_FOUND) - # Generate docs needs XML OUTPUT with sphinx + # Generate XML OUTPUT for breathe set(DOXYGEN_GENERATE_HTML NO) set(DOXYGEN_GENERATE_XML YES) + set(DOXYGEN_QUIET NO) + set(DOXYGEN_REFERENCED_BY_RELATION YES) + set(DOXYGEN_REFERENCES_LINK_SOURCE YES) + set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}) + set(doxygen_docs ${CMAKE_PROJECT_NAME}_doxygen) # cmake-format: off doxygen_add_docs( - ${CMAKE_PROJECT_NAME}_doxygen + ${doxygen_docs} "${CMAKE_BINARY_DIR}/git/include" - "${CMAKE_BINARY_DIR}/compile/include" + "${CMAKE_BINARY_DIR}/src/compile/include" "${PROJECT_SOURCE_DIR}/src/compile/include" "${PROJECT_SOURCE_DIR}/src/executable/include" - "${PROJECT_SOURCE_DIR}/src/header_only/include" - COMMENT "gen doxygen style docs automatically") + "${PROJECT_SOURCE_DIR}/src/header_only/include") # cmake-format: on - if(TARGET ${CMAKE_PROJECT_NAME}_doxygen) - list(APPEND CMAKE_MODULE_PATH "${cmake-modules_MODULE_PATH}/configure") - find_package(Sphinx REQUIRED breathe) + if(TARGET ${doxygen_docs}) + set(Sphinx_FIND_COMPONENTS breathe) + include(cmake-modules/configure/FindSphinx) + unset(Sphinx_FIND_COMPONENTS) sphinx_add_docs( ${CMAKE_PROJECT_NAME}_docs BREATHE_PROJECTS - ${CMAKE_PROJECT_NAME}_doxygen + ${doxygen_docs} BUILDER html BREATH_DEBUG @@ -38,6 +43,6 @@ if(DOXYGEN_FOUND) SOURCE_DIRECTORY docs OUTPUT_DIRECTORY - ${CMAKE_PROJECT_NAME}_docs) + ${CMAKE_SOURCE_DIR}/docs/_build/html) endif() endif() diff --git a/docs/api.md b/docs/api.md index 9c2450d9..54d5840f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,6 +1,6 @@ -# API Documentation +# ss-cpp API -This documentation was generated by Doxygen + Breathe +This API was generated by Doxygen + Breathe ```{doxygenindex} :project: ss-cpp_doxygen diff --git a/docs/cmake_workflow.md b/docs/cmake_workflow.md index 7f45c5c4..acfe7432 100644 --- a/docs/cmake_workflow.md +++ b/docs/cmake_workflow.md @@ -1,6 +1,6 @@ -# CMake workflow +# CMake Workflow -CMake common workflow command. +## Without Presets ```bash # Configure @@ -13,7 +13,11 @@ cd build && ctest -C Debug -T test --output-on-failure cd build && ctest -C Debug -T memcheck # Install cmake --build build --config Debug --target install +``` + +## With Presets +```bash # with presets https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html cmake -S . --list-presets # list all configure presets cmake -S . --preset= # configure using desired configure preset diff --git a/docs/conf.py b/docs/conf.py index f8a776e5..76541a8b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,10 +27,13 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - # there may be others here already, e.g. 'sphinx.ext.mathjax' - "myst_parser", "breathe", + "myst_parser", "sphinx_copybutton", + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinxcontrib.moderncmakedomain", ] source_suffix = { ".rst": "restructuredtext", @@ -51,7 +54,7 @@ highlight_language = "cpp" cpp_id_attributes = [ - "compile_EXPORT", + "COMPILE_EXPORT", "GIT_EXTERN_C_BEGIN", ] diff --git a/docs/coverage.md b/docs/coverage.md deleted file mode 100644 index a8f9e5e7..00000000 --- a/docs/coverage.md +++ /dev/null @@ -1,5 +0,0 @@ -# Coverage Reports - -Coverage pages are generated externally. - - diff --git a/docs/index.md b/docs/index.md index 413921ba..7f91c5fc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,17 +2,35 @@ ```{toctree} :hidden: -Overview -cmake_workflow -changelog -api -coverage ``` + + ```{include} ../README.md :start-line: 1 ``` +## Content + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Guide +:glob: + +Overview +cmake_workflow +``` + +```{toctree} +:maxdepth: 1 +:titlesonly: +:caption: References + +api +changelog +``` + ## 🔖 Indices and tables * {ref}`genindex` diff --git a/docs/requirements.txt b/docs/requirements.txt index 8fb1bde1..991724ad 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,6 @@ -breathe -furo +breathe==4.35.0 +furo==2024.1.29 sphinx==7.1.2 -sphinx-copybutton -myst_parser +sphinx-copybutton==0.5.2 +myst-parser==2.0.0 +sphinxcontrib-moderncmakedomain==3.27.0 diff --git a/src/compile/CMakeLists.txt b/src/compile/CMakeLists.txt index 1d53b8c8..b0045a61 100644 --- a/src/compile/CMakeLists.txt +++ b/src/compile/CMakeLists.txt @@ -13,13 +13,12 @@ target_code_coverage(${target_name}-shared ALL) include(GenerateExportHeader) generate_export_header( ${target_name}-shared BASE_NAME "${target_name}" EXPORT_FILE_NAME - "${CMAKE_CURRENT_BINARY_DIR}/include/${target_name}/${target_name}_export.hpp" -) + "${CMAKE_CURRENT_BINARY_DIR}/include/${target_name}_export.hpp") target_sources(${target_name}-shared PRIVATE ${_srcs} ${_hdrs}) target_include_interface_directories( - ${target_name}-shared ${CMAKE_CURRENT_BINARY_DIR}/include/${target_name} + ${target_name}-shared ${CMAKE_CURRENT_BINARY_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/include ${CMAKE_BINARY_DIR}/git/include) target_compile_options( @@ -50,7 +49,7 @@ target_compile_definitions(${target_name}-static INTERFACE ${target_name}_STATIC_DEFINE) target_include_interface_directories( - ${target_name}-static ${CMAKE_CURRENT_BINARY_DIR}/include/${target_name} + ${target_name}-static ${CMAKE_CURRENT_BINARY_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/include ${CMAKE_BINARY_DIR}/git/include) target_compile_options( @@ -87,7 +86,7 @@ install_target( ${CMAKE_PROJECT_VERSION} INCLUDES ${CMAKE_CURRENT_SOURCE_DIR}/include/ - ${CMAKE_CURRENT_BINARY_DIR}/include/${target_name}/ + ${CMAKE_CURRENT_BINARY_DIR}/include/ ${CMAKE_BINARY_DIR}/git/include/ LICENSE_FILE_LIST ${CMAKE_SOURCE_DIR}/LICENSE diff --git a/template/.gitignore.jinja b/template/.gitignore.jinja index 09cc4c5f..9146c35e 100644 --- a/template/.gitignore.jinja +++ b/template/.gitignore.jinja @@ -343,3 +343,6 @@ ASALocalRun/ # Ignore things from copier .copier-answers.yml [%- endif %] + +# Documenation files +docs/_build diff --git a/template/CMakeLists.txt.jinja b/template/CMakeLists.txt.jinja index 34738b69..a035a1a0 100644 --- a/template/CMakeLists.txt.jinja +++ b/template/CMakeLists.txt.jinja @@ -41,8 +41,6 @@ find_package(cmake-modules REQUIRED) include(cmake-modules/configure/Default) include(cmake-modules/configure/Common) include(cmake-modules/configure/CheckBuildDir) -include(cmake-modules/configure/ConfigDoxygen) -include(cmake-modules/configure/FindSphinx) include(cmake-modules/configure/UniqueOutputBinaryDir) include(cmake-modules/build/Default) include(cmake-modules/build/Ccache) @@ -60,11 +58,6 @@ include(cmake-modules/install/Runpath) # Add _DEBUG macro add_debug_macro() -# LTO for release -if(${CMAKE_BUILD_TYPE} MATCHES [[Release]]) - link_time_optimization() -endif() - create_uninstall_target() # Project custom modules diff --git a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/api.md.jinja b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/api.md.jinja index df57546a..e59dfb46 100644 --- a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/api.md.jinja +++ b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/api.md.jinja @@ -1,6 +1,6 @@ -# API Documentation +# {{ repo_name }} API -This documentation was generated by Doxygen + Breathe +This API was generated by Doxygen + Breathe ```{doxygenindex} :project: {{ repo_name }}_doxygen diff --git a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/cmake_workflow.md b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/cmake_workflow.md index 7f45c5c4..acfe7432 100644 --- a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/cmake_workflow.md +++ b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/cmake_workflow.md @@ -1,6 +1,6 @@ -# CMake workflow +# CMake Workflow -CMake common workflow command. +## Without Presets ```bash # Configure @@ -13,7 +13,11 @@ cd build && ctest -C Debug -T test --output-on-failure cd build && ctest -C Debug -T memcheck # Install cmake --build build --config Debug --target install +``` + +## With Presets +```bash # with presets https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html cmake -S . --list-presets # list all configure presets cmake -S . --preset= # configure using desired configure preset diff --git a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/conf.py.jinja b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/conf.py.jinja index c47a73af..d5dc2d5b 100644 --- a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/conf.py.jinja +++ b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/conf.py.jinja @@ -27,10 +27,13 @@ author = "{{ author_name }}" # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - # there may be others here already, e.g. 'sphinx.ext.mathjax' - "myst_parser", "breathe", + "myst_parser", "sphinx_copybutton", + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinxcontrib.moderncmakedomain", ] source_suffix = { ".rst": "restructuredtext", @@ -52,7 +55,7 @@ highlight_language = "cpp" cpp_id_attributes = [ [%- if add_compile_target == true %] - "compile_EXPORT", + "COMPILE_EXPORT", [%- endif %] "GIT_EXTERN_C_BEGIN", ] diff --git a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/coverage.md b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/coverage.md deleted file mode 100644 index a8f9e5e7..00000000 --- a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/coverage.md +++ /dev/null @@ -1,5 +0,0 @@ -# Coverage Reports - -Coverage pages are generated externally. - - diff --git a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/index.md.jinja b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/index.md.jinja index 591c3eae..9334f3a7 100644 --- a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/index.md.jinja +++ b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/index.md.jinja @@ -2,17 +2,35 @@ ```{toctree} :hidden: +``` + + + +```{include} ../README.md +:start-line: 1 +``` + +## Content + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Guide +:glob: + Overview [% if repo_name == 'ss-cpp' -%] cmake_workflow [% endif -%] -changelog -api -coverage ``` -```{include} ../README.md -:start-line: 1 +```{toctree} +:maxdepth: 1 +:titlesonly: +:caption: References + +api +changelog ``` ## 🔖 Indices and tables diff --git a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/requirements.txt b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/requirements.txt index 8fb1bde1..991724ad 100644 --- a/template/[% if docs_type == 'sphinx' %]docs[% endif %]/requirements.txt +++ b/template/[% if docs_type == 'sphinx' %]docs[% endif %]/requirements.txt @@ -1,5 +1,6 @@ -breathe -furo +breathe==4.35.0 +furo==2024.1.29 sphinx==7.1.2 -sphinx-copybutton -myst_parser +sphinx-copybutton==0.5.2 +myst-parser==2.0.0 +sphinxcontrib-moderncmakedomain==3.27.0 diff --git a/template/cmake/ConfigureCoverage.cmake b/template/cmake/ConfigureCoverage.cmake index 0ce01f28..13990b9a 100644 --- a/template/cmake/ConfigureCoverage.cmake +++ b/template/cmake/ConfigureCoverage.cmake @@ -6,9 +6,5 @@ add_code_coverage_all_targets( ${VCPKG_INSTALLED_DIR}/* ${CMAKE_BINARY_DIR}/* /usr/* - HTML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}_docs/coverage) + HTML_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/docs/_build/coverage) # cmake-format: on - -if(TARGET ${CMAKE_PROJECT_NAME}_docs) - add_dependencies(ccov-all ${CMAKE_PROJECT_NAME}_docs) -endif() diff --git a/template/cmake/ConfigureDocs.cmake.jinja b/template/cmake/ConfigureDocs.cmake.jinja index 42824b26..e9819c76 100644 --- a/template/cmake/ConfigureDocs.cmake.jinja +++ b/template/cmake/ConfigureDocs.cmake.jinja @@ -6,16 +6,21 @@ configdoxygen() if(DOXYGEN_FOUND) - # Generate docs needs XML OUTPUT with sphinx + # Generate XML OUTPUT for breathe set(DOXYGEN_GENERATE_HTML NO) set(DOXYGEN_GENERATE_XML YES) + set(DOXYGEN_QUIET NO) + set(DOXYGEN_REFERENCED_BY_RELATION YES) + set(DOXYGEN_REFERENCES_LINK_SOURCE YES) + set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}) + set(doxygen_docs ${CMAKE_PROJECT_NAME}_doxygen) # cmake-format: off doxygen_add_docs( - ${CMAKE_PROJECT_NAME}_doxygen + ${doxygen_docs} "${CMAKE_BINARY_DIR}/git/include" [%- if add_compile_target == true %] - "${CMAKE_BINARY_DIR}/compile/include" + "${CMAKE_BINARY_DIR}/src/compile/include" "${PROJECT_SOURCE_DIR}/src/compile/include" [%- endif %] [%- if add_executable_target == true %] @@ -23,18 +28,18 @@ if(DOXYGEN_FOUND) [%- endif %] [%- if add_header_only_target == true %] "${PROJECT_SOURCE_DIR}/src/header_only/include" -[%- endif %] - COMMENT "gen doxygen style docs automatically") +[%- endif %]) # cmake-format: on - if(TARGET ${CMAKE_PROJECT_NAME}_doxygen) - list(APPEND CMAKE_MODULE_PATH "${cmake-modules_MODULE_PATH}/configure") - find_package(Sphinx REQUIRED breathe) + if(TARGET ${doxygen_docs}) + set(Sphinx_FIND_COMPONENTS breathe) + include(cmake-modules/configure/FindSphinx) + unset(Sphinx_FIND_COMPONENTS) sphinx_add_docs( ${CMAKE_PROJECT_NAME}_docs BREATHE_PROJECTS - ${CMAKE_PROJECT_NAME}_doxygen + ${doxygen_docs} BUILDER html BREATH_DEBUG @@ -44,6 +49,6 @@ if(DOXYGEN_FOUND) SOURCE_DIRECTORY docs OUTPUT_DIRECTORY - ${CMAKE_PROJECT_NAME}_docs) + ${CMAKE_SOURCE_DIR}/docs/_build/html) endif() endif() diff --git a/template/src/[% if add_compile_target == true %]compile[% endif %]/CMakeLists.txt b/template/src/[% if add_compile_target == true %]compile[% endif %]/CMakeLists.txt index 1d53b8c8..b0045a61 100644 --- a/template/src/[% if add_compile_target == true %]compile[% endif %]/CMakeLists.txt +++ b/template/src/[% if add_compile_target == true %]compile[% endif %]/CMakeLists.txt @@ -13,13 +13,12 @@ target_code_coverage(${target_name}-shared ALL) include(GenerateExportHeader) generate_export_header( ${target_name}-shared BASE_NAME "${target_name}" EXPORT_FILE_NAME - "${CMAKE_CURRENT_BINARY_DIR}/include/${target_name}/${target_name}_export.hpp" -) + "${CMAKE_CURRENT_BINARY_DIR}/include/${target_name}_export.hpp") target_sources(${target_name}-shared PRIVATE ${_srcs} ${_hdrs}) target_include_interface_directories( - ${target_name}-shared ${CMAKE_CURRENT_BINARY_DIR}/include/${target_name} + ${target_name}-shared ${CMAKE_CURRENT_BINARY_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/include ${CMAKE_BINARY_DIR}/git/include) target_compile_options( @@ -50,7 +49,7 @@ target_compile_definitions(${target_name}-static INTERFACE ${target_name}_STATIC_DEFINE) target_include_interface_directories( - ${target_name}-static ${CMAKE_CURRENT_BINARY_DIR}/include/${target_name} + ${target_name}-static ${CMAKE_CURRENT_BINARY_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/include ${CMAKE_BINARY_DIR}/git/include) target_compile_options( @@ -87,7 +86,7 @@ install_target( ${CMAKE_PROJECT_VERSION} INCLUDES ${CMAKE_CURRENT_SOURCE_DIR}/include/ - ${CMAKE_CURRENT_BINARY_DIR}/include/${target_name}/ + ${CMAKE_CURRENT_BINARY_DIR}/include/ ${CMAKE_BINARY_DIR}/git/include/ LICENSE_FILE_LIST ${CMAKE_SOURCE_DIR}/LICENSE