Add Documentation Site

.github/workflows/build.yml

@@ -95,3 +95,21 @@ jobs:
           source-dir: ${{ matrix.package }}
           cxx-compiler: cl
           run-build: true
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3.5.3
+
+      - name: Install dependencies
+        run: pip3 install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: sphinx-build -b html docs build/docs -W --keep-going
+
+      - name: Upload documentation as artifact
+        uses: actions/upload-artifact@v3.1.2
+        with:
+          name: docs
+          path: build/docs

.gitignore

@@ -2,5 +2,6 @@
 !.clang*
 !.cmake*
 !.git*
+!.readthedocs*
 
 build

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+sphinx:
+   configuration: docs/conf.py
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/conf.py

@@ -0,0 +1,16 @@
+import os, subprocess
+
+project = 'cpp'
+copyright = '2023, Alfi Maulana'
+author = 'Alfi Maulana'
+
+extensions = ['breathe']
+
+subprocess.call('cmake ../error -B ../error/build -D BUILD_DOCS=ON', shell=True)
+subprocess.call('cmake --build ../error/build --target docs', shell=True)
+
+breathe_projects = {"error": "../error/build/docs"}
+breathe_default_project = "error"
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/error/index.rst

@@ -0,0 +1,51 @@
+Error Package
+=============
+
+A C++ package that provides utilities for error handling.
+
+API Docs
+--------
+
+.. doxygenfunction:: error::make
+
+.. doxygenfunction:: error::format
+
+.. doxygenstruct:: error::Error
+   :members:
+
+.. doxygenfunction:: error::operator==
+
+.. doxygenfunction:: error::operator!=
+
+License
+-------
+
+.. image:: https://opensource.org/wp-content/uploads/2022/10/osi-badge-dark.svg
+   :width: 150
+   :align: right
+   :target: https://opensource.org/licenses
+
+This project is licensed under the terms of the `MIT License`_.
+
+Copyright © 2023 `Alfi Maulana`_
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+.. _Alfi Maulana: https://github.com/threeal
+.. _MIT License: https://opensource.org/licenses/MIT

docs/index.rst

@@ -0,0 +1,47 @@
+Overview
+========
+
+A comprehensive collection of `C++`_ utility packages.
+
+.. _C++: https://isocpp.org
+
+Packages
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   error/index.rst
+
+License
+-------
+
+.. image:: https://opensource.org/wp-content/uploads/2022/10/osi-badge-dark.svg
+   :width: 150
+   :align: right
+   :target: https://opensource.org/licenses
+
+This project is licensed under the terms of the `MIT License`_.
+
+Copyright © 2023 `Alfi Maulana`_
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+.. _Alfi Maulana: https://github.com/threeal
+.. _MIT License: https://opensource.org/licenses/MIT

docs/requirements.txt

@@ -0,0 +1,3 @@
+breathe
+sphinx
+sphinx-rtd-theme

error/CMakeLists.txt

@@ -17,6 +17,7 @@ if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
   option(CHECK_FORMAT "Enable source code formatting check" OFF)
   option(CHECK_WARNING "Enable static analysis warning check" OFF)
   option(CHECK_COVERAGE "Enable test coverage check" OFF)
+  option(BUILD_DOCS "Enable documentations build" OFF)
 
   # Import Format.cmake to format source code
   if(CHECK_FORMAT)
@@ -56,4 +57,10 @@ if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
       target_link_options(${TARGET} PRIVATE --coverage)
     endif()
   endforeach()
+
+  # Build XML documentation
+  if(BUILD_DOCS)
+    include(cmake/add_xml_docs.cmake)
+    add_xml_docs(docs include/error/error.hpp)
+  endif()
 endif()

error/cmake/add_xml_docs.cmake

@@ -0,0 +1,30 @@
+# A function that generates XML documentation from the specified source files.
+function(add_xml_docs TARGET_NAME)
+  # Try to install Doxygen if not found
+  find_program(DOXYGEN_PROGRAM doxygen)
+  if(NOT DOXYGEN_PROGRAM)
+    find_program(APT_GET_PROGRAM apt-get)
+    if(APT_GET_PROGRAM)
+      message(STATUS "Doxygen could not be found, installing...")
+      execute_process(COMMAND sudo ${APT_GET_PROGRAM} install -y doxygen)
+    endif()
+
+    find_program(BREW_PROGRAM brew)
+    if(BREW_PROGRAM)
+      message(STATUS "Doxygen could not be found, installing...")
+      execute_process(COMMAND ${BREW_PROGRAM} install doxygen)
+    endif()
+  endif()
+
+  # Try to find Doxygen
+  find_package(Doxygen)
+  if(DOXYGEN_FOUND)
+    # Configure Doxygen to generate XML documentation
+    set(DOXYGEN_GENERATE_HTML NO)
+    set(DOXYGEN_GENERATE_XML YES)
+    set(DOXYGEN_XML_OUTPUT ${TARGET_NAME})
+
+    # Generate XML documentation for the target
+    doxygen_add_docs(${TARGET_NAME} ${ARGN} USE_STAMP_FILE)
+  endif()
+endfunction()