Docs fixes

CMakeLists.txt

@@ -1,13 +1,13 @@
 cmake_minimum_required(VERSION 3.17)
 
 get_property(is_multi_config GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
-if(is_multi_config)
+if (is_multi_config)
     set(CMAKE_CONFIGURATION_TYPES Debug Release CACHE STRING
-        "Semicolon separated list of supported configuration types")
+            "Semicolon separated list of supported configuration types")
     mark_as_advanced(CMAKE_CONFIGURATION_TYPES)
-elseif(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_C_FLAGS)
+elseif (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_C_FLAGS)
     message(WARNING "No CMAKE_BUILD_TYPE is selected")
-endif()
+endif ()
 
 project(j)
 enable_language(C CXX ASM)
@@ -16,9 +16,9 @@ set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
 
 include(CTest)
 
-if(PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
+if (PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
     set(BUILD_SHARED_LIBS ON)
-endif()
+endif ()
 
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED ON)
@@ -82,14 +82,33 @@ add_compile_options($<$<COMPILE_LANGUAGE:C>:-Wno-unknown-pragmas>)
 
 add_subdirectory(jsrc)
 add_subdirectory(base64)
+
+# see https://cliutils.gitlab.io/modern-cmake/chapters/projects/submodule.html for method used to have cmake git submodule
+find_package(Git REQUIRED)
+if (GIT_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
+    # Update submodules as needed
+    option(GIT_SUBMODULE "Check submodules during build" ON)
+    if (GIT_SUBMODULE)
+        message(STATUS "Submodule update")
+        execute_process(COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                RESULT_VARIABLE GIT_SUBMOD_RESULT)
+        if (NOT GIT_SUBMOD_RESULT EQUAL "0")
+            message(FATAL_ERROR "git submodule update --init failed with ${GIT_SUBMOD_RESULT}, please checkout submodules")
+        endif ()
+    endif ()
+endif ()
+if (NOT EXISTS "${PROJECT_SOURCE_DIR}/An-Algorithm-Library/CMakeLists.txt")
+    message(FATAL_ERROR "The submodules were not downloaded! GIT_SUBMODULE was turned off or failed. Please update submodules and try again.")
+endif ()
 add_subdirectory(An-Algorithm-Library EXCLUDE_FROM_ALL)
-if(${DOCS} STREQUAL "YES")
+if (${DOCS} STREQUAL "YES")
     add_subdirectory(docs)
-endif()
+endif ()
 
-if(BUILD_SHARED_LIBS)
+if (BUILD_SHARED_LIBS)
     set_target_properties(j-base64 PROPERTIES
-        POSITION_INDEPENDENT_CODE ON)
+            POSITION_INDEPENDENT_CODE ON)
     add_subdirectory(test)
-endif()
+endif ()
 target_link_libraries(j PRIVATE j-base64)

CONTRIBUTING.md

@@ -4,7 +4,7 @@
      * [Ubuntu CMake update instructions](https://apt.kitware.com/)
    * Ninja
    * Additional prerequisites for building the documentation:
-     * python packages: sphinx, breathe, divio-docs-theme
+     * python packages: sphinx, breathe, myst_parser, divio-docs-theme
      * doxygen
 2. Checkout the repository:
     ```sh

cmake/FindSphinx.cmake

@@ -1,11 +1,22 @@
-#Look for an executable called sphinx-build
-find_program(SPHINX_EXECUTABLE
-             NAMES sphinx-build
-             DOC "Path to sphinx-build executable")
+find_package (Python3 COMPONENTS Interpreter Development REQUIRED)
+
+execute_process(
+        COMMAND ${Python3_EXECUTABLE}  "-c" "exec(\"import sphinx\\nimport os\\nprint (os.path.dirname(sphinx.__file__))\")"
+        RESULT_VARIABLE EXIT_CODE
+        OUTPUT_VARIABLE PIP3_SPHINX_DATA
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+message(STATUS ${Python3_EXECUTABLE})
+message(STATUS ${PIP3_SPHINX_DATA}/bin)
+find_program(SPHINX_EXECUTABLE NAMES sphinx-build
+        HINTS ${PIP3_SPHINX_DATA} ~/.local/bin
+        DOC "Sphinx documentation generator"
+        )
 
 include(FindPackageHandleStandardArgs)
 
-#Handle standard arguments to find_package like REQUIRED and QUIET
-find_package_handle_standard_args(Sphinx
-                                  "Failed to find sphinx-build executable"
-                                  SPHINX_EXECUTABLE)
+find_package_handle_standard_args(Sphinx DEFAULT_MSG
+        SPHINX_EXECUTABLE
+        )
+
+mark_as_advanced(SPHINX_EXECUTABLE)

docs/CMakeLists.txt

@@ -1,9 +1,14 @@
 find_package(Doxygen REQUIRED)
 find_package(Sphinx REQUIRED)
 
-# Find all the public headers
+# Find all the public headers/source files
 get_target_property(J_PUBLIC_HEADER_DIR j INTERFACE_INCLUDE_DIRECTORIES)
-file(GLOB_RECURSE J_PUBLIC_HEADERS ${J_PUBLIC_HEADER_DIR}/*.h)
+file(GLOB_RECURSE J_PUBLIC_HEADERS
+        ${J_PUBLIC_HEADER_DIR}/*.h
+        ${J_PUBLIC_HEADER_DIR}/*.c
+        ${J_PUBLIC_HEADER_DIR}/*.hpp
+        ${J_PUBLIC_HEADER_DIR}/*.cpp
+        )
 
 set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/jsrc)
 
@@ -20,11 +25,11 @@ file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
 
 # Only regenerate Doxygen when the Doxyfile or public headers change
 add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
-                   DEPENDS ${J_PUBLIC_HEADERS}
-                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
-                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
-                   COMMENT "Generating docs"
-                   VERBATIM)
+        DEPENDS ${J_PUBLIC_HEADERS}
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+        MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+        COMMENT "Generating docs"
+        VERBATIM)
 
 # Nice named target so we can run the job easily
 add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
@@ -33,33 +38,34 @@ set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/source)
 set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
 set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
 
+file(GLOB_RECURSE SPHINX_SOURCE_SOURCE_CODE
+        ${SPHINX_SOURCE}/*.md
+        ${SPHINX_SOURCE}/*.rst
+        )
+
 # Only regenerate Sphinx when:
 # - Doxygen has rerun
 # - Our doc files have been updated
 # - The Sphinx config has been updated
 add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
-                   COMMAND 
-                     ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/scripts/preprocessor.py
-                     --input ${SPHINX_SOURCE}
-                     --output ${SPHINX_SOURCE}/__output__
-                     &&
-                     ${SPHINX_EXECUTABLE} -b html
-                     # Tell Breathe where to find the Doxygen output
-                     -Dbreathe_projects.jsrc=${DOXYGEN_OUTPUT_DIR}/xml
-                     -Dbreathe_default_project=jsrc
-                   ${SPHINX_SOURCE}/__output__ ${SPHINX_BUILD}
-                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-                   DEPENDS
-                   # Other docs files you want to track should go here (or in some variable)
-                   ${CMAKE_CURRENT_SOURCE_DIR}/source/index.rst
-                   ${DOXYGEN_INDEX_FILE}
-                   MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
-                   COMMENT "Generating documentation with Sphinx")
+        COMMAND
+        ${SPHINX_EXECUTABLE} -b html
+        # Tell Breathe where to find the Doxygen output
+        -Dbreathe_projects.jsrc=${DOXYGEN_OUTPUT_DIR}/xml
+        -Dbreathe_default_project=jsrc
+        ${SPHINX_SOURCE} ${SPHINX_BUILD}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        DEPENDS
+        # Other docs files you want to track should go here (or in some variable)
+        ${SPHINX_SOURCE_SOURCE_CODE}
+        ${DOXYGEN_INDEX_FILE}
+        MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+        COMMENT "Generating documentation with Sphinx")
 
 # Nice named target so we can run the job easily
 add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
 
 # Add an install target to install the docs
 include(GNUInstallDirs)
 install(DIRECTORY ${SPHINX_BUILD}
-DESTINATION ${CMAKE_INSTALL_DOCDIR})
+        DESTINATION ${CMAKE_INSTALL_DOCDIR})

docs/Doxyfile.in

@@ -1076,7 +1076,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1620,7 +1620,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of