diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f0ca665..8edc0fd 100644 --- a/.github/workflows/build.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index ee3c7e0..6ab56e3 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,6 @@ !.clang* !.cmake* !.git* +!.readthedocs* build diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..a376b46 --- /dev/null +++ b/.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 diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..1656c40 --- /dev/null +++ b/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'] diff --git a/docs/error/index.rst b/docs/error/index.rst new file mode 100644 index 0000000..20173cd --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..816a30a --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..28179ea --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +breathe +sphinx +sphinx-rtd-theme diff --git a/error/CMakeLists.txt b/error/CMakeLists.txt index d9b4656..2269aa9 100644 --- a/error/CMakeLists.txt +++ b/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() diff --git a/error/cmake/add_xml_docs.cmake b/error/cmake/add_xml_docs.cmake new file mode 100644 index 0000000..dfd02c3 --- /dev/null +++ b/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()