feat: generate documentation

fixes #1

.github/workflows/release.yml

@@ -21,17 +21,20 @@ jobs:
           git_commit_gpgsign: true
 
       - name: 'Install Build Tools'
-        run: 'sudo apt-get install --yes build-essential gcc make clang-format'
+        run: 'sudo apt-get install --yes build-essential gcc make clang-format doxygen doxygen-gui doxygen-doc graphviz'
 
       - run: 'make set_version'
 
+      - name: 'Generate Documentation'
+        run: 'make documentation'
+
       - name: 'Use Node.js'
         uses: 'actions/setup-node@v3.1.0'
         with:
           node-version: 'lts/*'
 
       - name: 'Install Release Tools'
-        run: 'npm install --save-dev semantic-release @commitlint/cli @commitlint/config-conventional @semantic-release/git @semantic-release/exec @saithodev/semantic-release-backmerge'
+        run: 'npm install --save-dev semantic-release @commitlint/cli @commitlint/config-conventional @semantic-release/git @semantic-release/exec @saithodev/semantic-release-backmerge vercel'
 
       - run: 'rm --force package.json package-lock.json'
 
@@ -41,3 +44,10 @@ jobs:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           GIT_COMMITTER_NAME: ${{ secrets.GIT_NAME }}
           GIT_COMMITTER_EMAIL: ${{ secrets.GIT_EMAIL }}
+
+      - name: 'Deploy to Vercel'
+        run: 'npx vercel ./documentation/html --token="${VERCEL_TOKEN}" --prod'
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}

.gitignore

@@ -6,3 +6,4 @@ bin
 *.exe
 *.a
 node_modules
+documentation

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "doxygen-awesome-css"]
+	path = doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

Doxyfile

@@ -0,0 +1,28 @@
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = libcproject
+PROJECT_BRIEF = "C static library easier to use than $(libc) (C standard library)."
+OUTPUT_DIRECTORY = documentation
+OUTPUT_LANGUAGE = English
+OPTIMIZE_OUTPUT_FOR_C = YES
+INPUT = ./
+INPUT_ENCODING = UTF-8
+USE_MDFILE_AS_MAINPAGE = README.md
+FILE_PATTERNS = *.h \
+  README.md
+HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css
+
+RECURSIVE = YES
+EXCLUDE = test doxygen-awesome-css
+GENERATE_LATEX = NO
+GENERATE_TREEVIEW = YES
+EXAMPLE_PATTERNS = *
+SOURCE_BROWSER = YES
+INLINE_SIMPLE_STRUCTS = YES
+EXTRACT_ALL = YES
+EXTRACT_STATIC = YES
+SORT_MEMBER_DOCS = NO
+FULL_SIDEBAR = NO
+DISABLE_INDEX = NO
+INLINE_SOURCES = YES
+LAYOUT_FILE = DoxygenLayout.xml
+HTML_INDEX_NUM_ENTRIES = 1

DoxygenLayout.xml

@@ -0,0 +1,57 @@
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.9.1 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="pages" visible="yes" title="" intro=""/>
+    <tab type="filelist" visible="yes" title="" intro=""/>
+  </navindex>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includegraph visible="$INCLUDE_GRAPH"/>
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <sourcelink visible="yes"/>
+    <memberdecl>
+      <interfaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <structs visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>

Makefile

@@ -39,6 +39,10 @@ test: all	 ${TEST_SOURCES}
 lint:
 	clang-format --Werror --dry-run ${LIB_SOURCES} ${TEST_SOURCES} ${HEADER_FILES} ./main.c
 
+.PHONY: documentation
+documentation:
+	doxygen ./Doxyfile
+
 .PHONY: clean
 clean:
-	rm --recursive --force ./build ./bin *.out *.o *.exe *.a
+	rm --recursive --force ./build ./bin *.out *.o *.exe *.a documentation

README.md

@@ -29,11 +29,13 @@ C is a low-level programming language and we often end up reinventing the wheel
 - [GNU gcc](https://gcc.gnu.org/)
 - [GNU make](https://www.gnu.org/software/make/)
 - [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
+- [Doxygen](https://www.doxygen.nl/)
 
 For example on GNU/Linux Ubuntu:
 
 ```sh
 sudo apt-get install build-essential gcc make clang-format
+sudo apt-get install doxygen doxygen-gui doxygen-doc graphviz
 ```
 
 ## Usage
@@ -43,6 +45,7 @@ make # to compile
 make run # to run main
 make test # to run unit tests
 make lint # to lint the code
+make documentation # to generate the documentation
 make clean # to clean up
 
 nm ./build/libcproject.a # to see the symbols