Skip to content

Commit 7a5902b

Browse files
threealthreeal
authored
chore: merge pull request #34 from threeal/add-documentation
Add Documentation Site
2 parents 071bd37 + 8f39251 commit 7a5902b

File tree

10 files changed

+183
-0
lines changed

10 files changed

+183
-0
lines changed

‎.github/workflows/build.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,21 @@ jobs:
9595
source-dir: ${{ matrix.package }}
9696
cxx-compiler: cl
9797
run-build: true
98+
99+
docs:
100+
runs-on: ubuntu-latest
101+
steps:
102+
- name: Checkout repository
103+
uses: actions/checkout@v3.5.3
104+
105+
- name: Install dependencies
106+
run: pip3 install -r docs/requirements.txt
107+
108+
- name: Build documentation
109+
run: sphinx-build -b html docs build/docs -W --keep-going
110+
111+
- name: Upload documentation as artifact
112+
uses: actions/upload-artifact@v3.1.2
113+
with:
114+
name: docs
115+
path: build/docs

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@
22
!.clang*
33
!.cmake*
44
!.git*
5+
!.readthedocs*
56

67
build

‎.readthedocs.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
version: 2
2+
build:
3+
os: ubuntu-22.04
4+
tools:
5+
python: "3.9"
6+
sphinx:
7+
configuration: docs/conf.py
8+
python:
9+
install:
10+
- requirements: docs/requirements.txt

‎docs/_static/.gitkeep

Whitespace-only changes.

‎docs/conf.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import os, subprocess
2+
3+
project = 'cpp'
4+
copyright = '2023, Alfi Maulana'
5+
author = 'Alfi Maulana'
6+
7+
extensions = ['breathe']
8+
9+
subprocess.call('cmake ../error -B ../error/build -D BUILD_DOCS=ON', shell=True)
10+
subprocess.call('cmake --build ../error/build --target docs', shell=True)
11+
12+
breathe_projects = {"error": "../error/build/docs"}
13+
breathe_default_project = "error"
14+
15+
html_theme = 'sphinx_rtd_theme'
16+
html_static_path = ['_static']

‎docs/error/index.rst

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Error Package
2+
=============
3+
4+
A C++ package that provides utilities for error handling.
5+
6+
API Docs
7+
--------
8+
9+
.. doxygenfunction:: error::make
10+
11+
.. doxygenfunction:: error::format
12+
13+
.. doxygenstruct:: error::Error
14+
:members:
15+
16+
.. doxygenfunction:: error::operator==
17+
18+
.. doxygenfunction:: error::operator!=
19+
20+
License
21+
-------
22+
23+
.. image:: https://opensource.org/wp-content/uploads/2022/10/osi-badge-dark.svg
24+
:width: 150
25+
:align: right
26+
:target: https://opensource.org/licenses
27+
28+
This project is licensed under the terms of the `MIT License`_.
29+
30+
Copyright © 2023 `Alfi Maulana`_
31+
32+
Permission is hereby granted, free of charge, to any person obtaining a copy
33+
of this software and associated documentation files (the "Software"), to deal
34+
in the Software without restriction, including without limitation the rights
35+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
36+
copies of the Software, and to permit persons to whom the Software is
37+
furnished to do so, subject to the following conditions:
38+
39+
The above copyright notice and this permission notice shall be included in all
40+
copies or substantial portions of the Software.
41+
42+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
43+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
44+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
45+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
46+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
47+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
48+
SOFTWARE.
49+
50+
.. _Alfi Maulana: https://github.com/threeal
51+
.. _MIT License: https://opensource.org/licenses/MIT

‎docs/index.rst

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
Overview
2+
========
3+
4+
A comprehensive collection of `C++`_ utility packages.
5+
6+
.. _C++: https://isocpp.org
7+
8+
Packages
9+
--------
10+
11+
.. toctree::
12+
:maxdepth: 1
13+
14+
error/index.rst
15+
16+
License
17+
-------
18+
19+
.. image:: https://opensource.org/wp-content/uploads/2022/10/osi-badge-dark.svg
20+
:width: 150
21+
:align: right
22+
:target: https://opensource.org/licenses
23+
24+
This project is licensed under the terms of the `MIT License`_.
25+
26+
Copyright © 2023 `Alfi Maulana`_
27+
28+
Permission is hereby granted, free of charge, to any person obtaining a copy
29+
of this software and associated documentation files (the "Software"), to deal
30+
in the Software without restriction, including without limitation the rights
31+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
32+
copies of the Software, and to permit persons to whom the Software is
33+
furnished to do so, subject to the following conditions:
34+
35+
The above copyright notice and this permission notice shall be included in all
36+
copies or substantial portions of the Software.
37+
38+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
39+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
40+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
41+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
42+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
43+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
44+
SOFTWARE.
45+
46+
.. _Alfi Maulana: https://github.com/threeal
47+
.. _MIT License: https://opensource.org/licenses/MIT

‎docs/requirements.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
breathe
2+
sphinx
3+
sphinx-rtd-theme

‎error/CMakeLists.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
1717
option(CHECK_FORMAT "Enable source code formatting check" OFF)
1818
option(CHECK_WARNING "Enable static analysis warning check" OFF)
1919
option(CHECK_COVERAGE "Enable test coverage check" OFF)
20+
option(BUILD_DOCS "Enable documentations build" OFF)
2021

2122
# Import Format.cmake to format source code
2223
if(CHECK_FORMAT)
@@ -56,4 +57,10 @@ if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
5657
target_link_options(${TARGET} PRIVATE --coverage)
5758
endif()
5859
endforeach()
60+
61+
# Build XML documentation
62+
if(BUILD_DOCS)
63+
include(cmake/add_xml_docs.cmake)
64+
add_xml_docs(docs include/error/error.hpp)
65+
endif()
5966
endif()

‎error/cmake/add_xml_docs.cmake

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# A function that generates XML documentation from the specified source files.
2+
function(add_xml_docs TARGET_NAME)
3+
# Try to install Doxygen if not found
4+
find_program(DOXYGEN_PROGRAM doxygen)
5+
if(NOT DOXYGEN_PROGRAM)
6+
find_program(APT_GET_PROGRAM apt-get)
7+
if(APT_GET_PROGRAM)
8+
message(STATUS "Doxygen could not be found, installing...")
9+
execute_process(COMMAND sudo ${APT_GET_PROGRAM} install -y doxygen)
10+
endif()
11+
12+
find_program(BREW_PROGRAM brew)
13+
if(BREW_PROGRAM)
14+
message(STATUS "Doxygen could not be found, installing...")
15+
execute_process(COMMAND ${BREW_PROGRAM} install doxygen)
16+
endif()
17+
endif()
18+
19+
# Try to find Doxygen
20+
find_package(Doxygen)
21+
if(DOXYGEN_FOUND)
22+
# Configure Doxygen to generate XML documentation
23+
set(DOXYGEN_GENERATE_HTML NO)
24+
set(DOXYGEN_GENERATE_XML YES)
25+
set(DOXYGEN_XML_OUTPUT ${TARGET_NAME})
26+
27+
# Generate XML documentation for the target
28+
doxygen_add_docs(${TARGET_NAME} ${ARGN} USE_STAMP_FILE)
29+
endif()
30+
endfunction()

0 commit comments

Comments
 (0)