docs: simplify docs build (#64)

Signed-off-by: msclock <msclock@qq.com>
serious-scaffold · Mar 5, 2024 · ed57817 · ed57817
1 parent ca93006
commit ed57817
Show file tree

Hide file tree

Showing 22 changed files with 128 additions and 96 deletions.
diff --git 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
@@ -38,8 +38,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)
@@ -57,11 +55,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
@@ -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
@@ -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}/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
@@ -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
@@ -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=<preset>      # configure using desired configure preset

diff --git 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
diff --git a/docs/index.md b/docs/index.md
@@ -2,19 +2,35 @@
 
 ```{toctree}
 :hidden:
-Overview <self>
-cmake_workflow
-development
-contributing
-changelog
-api
-coverage
 ```
 
+<!-- Extract content from start line 1 of README.md -->
+
 ```{include} ../README.md
 :start-line: 1
 ```
 
+## Content
+
+```{toctree}
+:maxdepth: 2
+:titlesonly:
+:caption: Guide
+:glob:
+
+Overview <self>
+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
@@ -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
@@ -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
@@ -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
@@ -40,8 +40,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)
@@ -59,11 +57,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
@@ -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
@@ -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=<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
@@ -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
diff --git 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:
+```
+
+<!-- Extract content from start line 1 of README.md -->
+
+```{include} ../README.md
+:start-line: 1
+```
+
+## Content
+
+```{toctree}
+:maxdepth: 2
+:titlesonly:
+:caption: Guide
+:glob:
+
 Overview <self>
 [% 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
@@ -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
@@ -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()