Start adding documentation

.gitignore

@@ -8,3 +8,5 @@ msvc/
 src/revision.hpp
 test/test-create_sugar_?.cif
 Testing/
+docs/api
+

.readthedocs.yaml

+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+  apt_packages:
+    - "doxygen"
+    - "cmake"
+  jobs:
+    pre_build:
+      - "cmake -S . -B build -DBUILD_DOCUMENTATION=ON"
+      - "cmake --build build --target Doxygen"
+
+# Build from the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: docs/requirements.txt

CMakeLists.txt

@@ -52,6 +52,9 @@ endif()
 # Building shared libraries?
 option(BUILD_SHARED_LIBS "Build a shared library instead of a static one" OFF)
 
+# Build documentation?
+option(BUILD_DOC "Build the documentation" OFF)
+
 # We do not want to write an export file for all our symbols...
 set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
 
@@ -475,6 +478,10 @@ if(CIFPP_INSTALL_UPDATE_SCRIPT)
 	target_compile_definitions(cifpp PUBLIC CACHE_DIR="${CIFPP_CACHE_DIR}")
 endif()
 
+if(BUILD_DOC)
+	add_subdirectory(docs)
+endif()
+
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
 set(CPACK_SOURCE_TGZ ON)
 set(CPACK_SOURCE_TBZ2 OFF)

cmake/FindSphinx.cmake

+#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

docs/CMakeLists.txt

+find_package(Doxygen REQUIRED)
+find_package(Sphinx REQUIRED)
+
+# Find all the public headers
+# get_target_property(MCFP_PUBLIC_HEADER_DIR libmcfp INTERFACE_INCLUDE_DIRECTORIES)
+set(MCFP_PUBLIC_HEADER_DIR ${PROJECT_SOURCE_DIR}/include)
+file(GLOB_RECURSE MCFP_PUBLIC_HEADERS ${MCFP_PUBLIC_HEADER_DIR}/*.hpp)
+
+set(DOXYGEN_INPUT_DIR ${MCFP_PUBLIC_HEADER_DIR})
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+#Replace variables inside @@ with the current values
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) #Doxygen won't create this for us
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+                   DEPENDS ${MCFP_PUBLIC_HEADERS}
+                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+                   COMMENT "Generating docs")
+
+add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+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 ALL
+                  COMMAND
+                  ${SPHINX_EXECUTABLE} -b html
+				  -Dbreathe_projects.${PROJECT_NAME}=${DOXYGEN_OUTPUT_DIR}/xml
+                  ${SPHINX_SOURCE} ${SPHINX_BUILD}
+				  DEPENDS ${DOXYGEN_INDEX_FILE}
+                  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                  COMMENT "Generating documentation with Sphinx")
+
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/sphinx/ DESTINATION ${CMAKE_INSTALL_DOCDIR} PATTERN .doctrees EXCLUDE)

docs/Doxyfile.in

+EXCLUDE_SYMBOLS        = cif::detail::*, std*
+FILE_PATTERNS          = *.hpp
+RECURSIVE              = YES
+GENERATE_XML           = YES
+GENERATE_HTML          = NO
+GENERATE_TODOLIST      = NO
+INPUT                  = @DOXYGEN_INPUT_DIR@

docs/_static/.gitignore

+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

docs/conf.py

+project = 'libmcfp'
+copyright = '2023, Maarten L. Hekkelman'
+author = 'Maarten L. Hekkelman'
+release = '5.1.3'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "breathe",
+    "exhale",
+    "myst_parser"
+]
+
+breathe_projects = {
+	"libcifpp": "../build/docs/xml"
+}
+
+myst_enable_extensions = [ "colon_fence" ]
+breathe_default_project = "libcifpp"
+
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./api",
+    "rootFileName":          "library_root.rst",
+    "doxygenStripFromPath":  "../include/",
+    # Heavily encouraged optional argument (see docs)
+    "rootFileTitle":         "API Reference",
+    # Suggested optional arguments
+    # "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": False,
+    "contentsDirectives" : False,
+    
+    "verboseBuild": False
+}
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = 'cpp'
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = 'cpp'
+
+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 = {
+}
+
+cpp_index_common_prefix = [
+	'cif::'
+]
+

docs/conf.py.in

+project = 'libmcfp'
+copyright = '2023, Maarten L. Hekkelman'
+author = 'Maarten L. Hekkelman'
+release = '@PROJECT_VERSION@'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "breathe",
+    "exhale",
+    "myst_parser"
+]
+
+breathe_projects = {
+	"@PROJECT_NAME@": "../build/docs/xml"
+}
+
+myst_enable_extensions = [ "colon_fence" ]
+breathe_default_project = "@PROJECT_NAME@"
+
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./api",
+    "rootFileName":          "library_root.rst",
+    "doxygenStripFromPath":  "../include/",
+    # Heavily encouraged optional argument (see docs)
+    "rootFileTitle":         "API Reference",
+    # Suggested optional arguments
+    # "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": False,
+    "contentsDirectives" : False,
+    
+    "verboseBuild": False
+}
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = 'cpp'
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = 'cpp'
+
+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 = {
+}
+
+cpp_index_common_prefix = [
+	'cif::'
+]
+

docs/genindex.rst

+Index
+=====

docs/index.rst

+Introduction
+============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   self
+   api/library_root.rst
+   genindex.rst
+

docs/requirements.in

+sphinx<5
+exhale==0.3.6
+myst-parser
+breathe
+sphinx_rtd_theme==1.3.0

docs/requirements.txt

+#
+# 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

include/cif++/atom_type.hpp

@@ -35,8 +35,11 @@
 namespace cif
 {
 
+/// Atom type as an integer. All known elements are available as a constant.
+
 enum atom_type : uint8_t
 {
+/// @cond
 	Nn = 0, // Unknown
 
 	H = 1,  // Hydro­gen
@@ -169,6 +172,8 @@ enum atom_type : uint8_t
 	D = 119, // Deuterium
 };
 
+/// @endcond
+
 // --------------------------------------------------------------------
 // atom_type_info