add sphinx-built documentation

CMakeLists.txt

@@ -12,6 +12,7 @@ set(CMAKE_VERBOSE_MAKEFILE ON)
 
 # Use C++14
 set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # Define the library source files
 set(SOURCE_FILES
@@ -39,31 +40,64 @@ set(SOURCE_FILES
         src/lib/impl_/macros.hpp
         src/lib/impl_/internal_fwd_defs.hpp)
 
-include_directories(src/include)
-
 # Create the library archive for static linking
-add_library(omega_edit STATIC ${SOURCE_FILES})
+add_library(omega_edit ${SOURCE_FILES})
+target_include_directories(omega_edit PUBLIC src/include)
 
 # Parse version information
 string(TOUPPER ${PROJECT_NAME} PREFIX)
-string(REGEX REPLACE "^([0-9]+)\\.[0-9]+\\.[0-9]+.*" "\\1" ${PREFIX}_VERSION_MAJOR "${PROJECT_VERSION}")
-string(REGEX REPLACE "^[0-9]+\\.([0-9]+)\\.[0-9]+.*" "\\1" ${PREFIX}_VERSION_MINOR "${PROJECT_VERSION}")
-string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]+).*" "\\1" ${PREFIX}_VERSION_PATCH "${PROJECT_VERSION}")
 
 # Send version information into libomega_edit through macro definitions
 foreach(level MAJOR MINOR PATCH)
-    target_compile_definitions(omega_edit PRIVATE ${PREFIX}_VERSION_${level}=${${PREFIX}_VERSION_${level}})
+    target_compile_definitions(omega_edit PRIVATE ${PREFIX}_VERSION_${level}=${${PROJECT_NAME}_VERSION_${level}})
 endforeach()
 
-# Generate documentation using Doxygen
-find_package(Doxygen OPTIONAL_COMPONENTS dot dia mscgen)
-if(DOXYGEN_FOUND)
-    set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
-    set(DOXYGEN_EXTRACT_ALL YES)
-    set(DOXYGEN_OUTPUT_DIRECTORY docs)
-    doxygen_add_docs(docs src/omega_edit)
-endif(DOXYGEN_FOUND)
+option(BUILD_DOCS "build documentation" ON)
+if(BUILD_DOCS)
+    # Generate API documentation using Doxygen
+    find_package(Doxygen OPTIONAL_COMPONENTS dot dia mscgen)
+    if(DOXYGEN_FOUND)
+        set(DOXYGEN_GENERATE_HTML YES)
+        set(DOXYGEN_GENERATE_MAN YES)
+        set(DOXYGEN_GENERATE_XML YES)
+        set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
+        set(DOXYGEN_EXTRACT_ALL YES)
+        set(DOXYGEN_OUTPUT_DIRECTORY docs)
+        doxygen_add_docs(docs src/include ALL)
+        # Add the cmake folder so the FindSphinx module is found
+        set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+        find_package(Sphinx REQUIRED)
+        if(SPHINX_FOUND)
+            # Generate user documentation using Sphinx
+            set(DOXYGEN_INDEX_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/xml)
+            set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/sphinx)
+            set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+            set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+            add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+                    COMMAND ${SPHINX_EXECUTABLE} -b html
+                    # Tell Breathe where to find the Doxygen output
+                    -Dbreathe_projects.omega_edit=${DOXYGEN_INDEX_DIR}
+                    ${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}/index.rst
+                    ${DOXYGEN_INDEX_DIR}/index.xml
+                    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_dependencies(sphinx docs)
+            include(GNUInstallDirs)
+            install(DIRECTORY ${SPHINX_BUILD} DESTINATION ${CMAKE_INSTALL_DOCDIR})
+        else(SPHINX_FOUND)
+            message("Sphinx need to be installed to generate user documentation")
+        endif(SPHINX_FOUND)
+    else(DOXYGEN_FOUND)
+        message("Doxygen need to be installed to generate API documentation")
+    endif(DOXYGEN_FOUND)
+endif(BUILD_DOCS)
 
 # Add additional subdirectories with CMakeLists.txt to the build
-add_subdirectory(src/tests)
 add_subdirectory(src/examples)
+add_subdirectory(src/tests)

cmake/FindSphinx.cmake

@@ -0,0 +1,10 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+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)

sphinx/conf.py

@@ -0,0 +1,87 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+breathe_projects = {"omega_edit": ""}
+
+# -- Project information -----------------------------------------------------
+
+project = 'omega_edit'
+copyright = '2021-2022, Concurrent Technologies Corporation'
+author = 'Concurrent Technologies Corporation'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+#...
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx_sitemap',
+    'sphinx.ext.inheritance_diagram',
+    'breathe'
+]
+
+#...
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+highlight_language = 'c++'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'canonical_url': '',
+    'analytics_id': '',  #  Provided by Google in your dashboard
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': False,
+
+    'logo_only': False,
+
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
+
+# 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']
+
+# Breathe Configuration
+breathe_default_project = "omega_edit"

sphinx/index.rst

@@ -0,0 +1,89 @@
+.. ΩEdit documentation master file
+
+Welcome to ΩEdit's documentation!
+=================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+:ref:`genindex`
+
+byte.h
+------
+
+.. doxygenfile:: byte.h
+
+change.h
+--------
+
+.. doxygenfile:: change.h
+
+check.h
+-------
+
+.. doxygenfile:: check.h
+
+config.h
+--------
+
+.. doxygenfile:: config.h
+
+edit.h
+------
+.. doxygenfile:: edit.h
+
+encodings.h
+-----------
+
+.. doxygenfile:: encodings.h
+
+fwd_defs.h
+----------
+
+.. doxygenfile:: fwd_defs.h
+
+license.h
+---------
+
+.. doxygenfile:: license.h
+
+scoped_ptr.hpp
+--------------
+
+.. doxygenfile:: scoped_ptr.hpp
+
+search.h
+--------
+
+.. doxygenfile:: search.h
+
+session.h
+---------
+
+.. doxygenfile:: session.h
+
+stl_string_adaptor.hpp
+----------------------
+
+.. doxygenfile:: stl_string_adaptor.hpp
+
+utility.h
+---------
+
+.. doxygenfile:: utility.h
+
+version.h
+---------
+
+.. doxygenfile:: version.h
+
+viewport.h
+----------
+
+.. doxygenfile:: viewport.h
+
+visit.h
+-------
+
+.. doxygenfile:: visit.h

src/examples/CMakeLists.txt

@@ -1,3 +1,6 @@
+get_target_property(OMEGA_EDIT_PUBLIC_HEADER_DIR omega_edit INTERFACE_INCLUDE_DIRECTORIES)
+include_directories(${OMEGA_EDIT_PUBLIC_HEADER_DIR})
+
 add_executable(replace replace.cpp)
 target_link_libraries(replace omega_edit)
 

src/tests/CMakeLists.txt

@@ -1,11 +1,16 @@
+get_target_property(OMEGA_EDIT_PUBLIC_HEADER_DIR omega_edit INTERFACE_INCLUDE_DIRECTORIES)
+include_directories(${OMEGA_EDIT_PUBLIC_HEADER_DIR})
+
+add_executable(generate_file generate_file.cpp test_util.h)
+
 add_executable(omega_test omega_test.cpp test_util.h)
 target_link_libraries(omega_test omega_edit)
-add_custom_command(TARGET omega_test POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/src/tests/data/ $<TARGET_FILE_DIR:omega_test>/data)
+add_custom_command(TARGET omega_test
+    POST_BUILD COMMAND ${CMAKE_COMMAND}
+        -E copy_directory ${CMAKE_SOURCE_DIR}/src/tests/data/ $<TARGET_FILE_DIR:omega_test>/data)
 
 add_executable(play play.cpp)
 target_link_libraries(play omega_edit)
 
 add_executable(replay replay.cpp)
 target_link_libraries(replay omega_edit)
-
-add_executable(generate_file generate_file.cpp test_util.h)