From 50931e7e5837e5764a42fcafc7f2aacdd31fa740 Mon Sep 17 00:00:00 2001 From: "Maarten L. Hekkelman" Date: Mon, 25 Sep 2023 08:05:01 +0200 Subject: [PATCH] with initial docs --- CMakeLists.txt | 6 +++ cmake/FindSphinx.cmake | 11 +++++ docs/CMakeLists.txt | 16 +++++++ docs/_static/.gitignore | 4 ++ docs/conf.py.in | 29 +++++++++++++ docs/genindex.rst | 2 + docs/index.rst | 13 ++++++ docs/requirements.in | 5 +++ docs/requirements.txt | 93 +++++++++++++++++++++++++++++++++++++++++ 9 files changed, 179 insertions(+) create mode 100644 cmake/FindSphinx.cmake create mode 100644 docs/CMakeLists.txt create mode 100644 docs/_static/.gitignore create mode 100644 docs/conf.py.in create mode 100644 docs/genindex.rst create mode 100644 docs/index.rst create mode 100644 docs/requirements.in create mode 100644 docs/requirements.txt diff --git a/CMakeLists.txt b/CMakeLists.txt index 021891b..1ce90c9 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -44,6 +44,8 @@ set(CXX_EXTENSIONS OFF) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) +option(BUILD_DOCUMENTATION "Build the documentation" OFF) + if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU") set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Wno-unused-parameter -Wno-missing-field-initializers") elseif(MSVC) @@ -202,4 +204,8 @@ if(NOT USE_RSRC) ${PROJECT_SOURCE_DIR}/docroot DESTINATION ${ALPHAFILL_DATA_DIR} ) +endif() + +if(BUILD_DOCUMENTATION) + add_subdirectory(docs) endif() \ No newline at end of file diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake new file mode 100644 index 0000000..1382309 --- /dev/null +++ b/cmake/FindSphinx.cmake @@ -0,0 +1,11 @@ +#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) \ No newline at end of file diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000..0153d7d --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,16 @@ +find_package(Sphinx REQUIRED) + +configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_SOURCE_DIR}/conf.py @ONLY) + +set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}) +set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx) + +add_custom_target("Sphinx-${PROJECT_NAME}" ALL + COMMAND ${SPHINX_EXECUTABLE} -b html + ${SPHINX_SOURCE} ${SPHINX_BUILD} + COMMENT "Generating documentation with Sphinx") + +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/sphinx/ + DESTINATION ${CMAKE_INSTALL_DOCDIR} + PATTERN .doctrees EXCLUDE + PATTERN .buildinfo EXCLUDE) diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore new file mode 100644 index 0000000..5e7d273 --- /dev/null +++ b/docs/_static/.gitignore @@ -0,0 +1,4 @@ +# Ignore everything in this directory +* +# Except this file +!.gitignore diff --git a/docs/conf.py.in b/docs/conf.py.in new file mode 100644 index 0000000..8cbae98 --- /dev/null +++ b/docs/conf.py.in @@ -0,0 +1,29 @@ +project = '@PROJECT_NAME@' +copyright = '2023, Maarten L. Hekkelman' +author = 'Maarten L. Hekkelman' +release = '@PROJECT_VERSION@' + +# -- General configuration --------------------------------------------------- + +#extensions = [ +# "myst_parser" +#] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# -- 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' + +# 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'] + +html_theme_options = { +} + diff --git a/docs/genindex.rst b/docs/genindex.rst new file mode 100644 index 0000000..9e530fa --- /dev/null +++ b/docs/genindex.rst @@ -0,0 +1,2 @@ +Index +===== diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..cb3907c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,13 @@ +Introduction +============ + +.. literalinclude:: ../README.md + :language: md + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + self + genindex.rst + diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000..19c523a --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,5 @@ +sphinx<5 +exhale==0.3.6 +myst-parser +breathe +sphinx_rtd_theme==1.3.0 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..756ea89 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,93 @@ +# +# This file is autogenerated by pip-compile with Python 3.10 +# by the following command: +# +# pip-compile --output-file=requirements.txt requirements.in +# +alabaster==0.7.13 + # via sphinx +babel==2.12.1 + # via sphinx +beautifulsoup4==4.12.2 + # via exhale +breathe==4.35.0 + # via + # -r requirements.in + # exhale +certifi==2023.7.22 + # via requests +charset-normalizer==3.2.0 + # via requests +docutils==0.17.1 + # via + # breathe + # exhale + # myst-parser + # sphinx + # sphinx-rtd-theme +exhale==0.3.6 + # via -r requirements.in +idna==3.4 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.2 + # via + # myst-parser + # sphinx +lxml==4.9.3 + # via exhale +markdown-it-py==2.2.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.3 + # via jinja2 +mdit-py-plugins==0.3.5 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==0.18.1 + # via -r requirements.in +packaging==23.1 + # via sphinx +pygments==2.16.1 + # via sphinx +pyyaml==6.0.1 + # via myst-parser +requests==2.31.0 + # via sphinx +six==1.16.0 + # via exhale +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.4.1 + # via beautifulsoup4 +sphinx==4.5.0 + # via + # -r requirements.in + # breathe + # exhale + # myst-parser + # sphinx-rtd-theme + # sphinxcontrib-jquery +sphinx-rtd-theme==1.3.0 + # via -r requirements.in +sphinxcontrib-applehelp==1.0.4 + # via sphinx +sphinxcontrib-devhelp==1.0.2 + # via sphinx +sphinxcontrib-htmlhelp==2.0.1 + # via sphinx +sphinxcontrib-jquery==4.1 + # via sphinx-rtd-theme +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.3 + # via sphinx +sphinxcontrib-serializinghtml==1.1.5 + # via sphinx +typing-extensions==4.7.1 + # via myst-parser +urllib3==2.0.4 + # via requests