Tools: Add build documentation

This tool downloads and extracts doxygen and doxygen-awesome-css. The it builds the documentation website using doxygen, writing results to _Build/_Documentation/docs.
Pagghiu · Apr 9, 2024 · b654096 · b654096
1 parent 4e38dea
commit b654096
Show file tree

Hide file tree

Showing 30 changed files with 663 additions and 112 deletions.
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -148,6 +148,27 @@
             "problemMatcher": [
                 "$gcc"
             ],
-        }
+        },
+        {
+            "label": "Build Documentation",
+            "type": "shell",
+            "command": "${workspaceRoot}/SC.sh",
+            "args": [
+                "build",
+                "documentation"
+            ],
+            "windows": {
+                "command": "${workspaceRoot}/SC.bat",
+            },
+            "problemMatcher": [
+                "$gcc"
+            ],
+        },
+        {
+            "label": "Launch Documentation WebServer",
+            "type": "shell",
+            "command": "python3 -m http.server --directory ${workspaceRoot}/_Build/_Documentation/docs",
+            "problemMatcher": []
+        },
     ]
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
 
 > Note: this document will be updated regularly clarifying existing rules and adding missing guidelines that will emerge from discussions or PRs being reviewed.
 
-Before deep diving in this document, please take some time to read the [Principles](https://pagghiu.github.io/SaneCppLibraries/page_principles.html) and [Coding Style](Documentation/CodingStyle.md).  
+Before deep diving in this document, please take some time to read the [Principles](https://pagghiu.github.io/SaneCppLibraries/page_principles.html) and [Coding Style](https://pagghiu.github.io/SaneCppLibraries/page_coding_style.html).  
 More importantly browse the existing codebase!
 
 ## TLDR

diff --git a/Documentation/Doxygen/Doxyfile b/Documentation/Doxygen/Doxyfile
@@ -0,0 +1,105 @@
+# Compile using Doxyfile 1.9.2 because:
+# - Version 1.9.5 / 1.9.6 breaks the library recap table
+# - Version 1.9.7 has a bug that prevents showing TOC on subpages
+# - Version 1.9.8 has a bug that prevents showing modules and confuses with SC::Array, SC::Span, SC::SegmentItems, SC::forward
+
+PROJECT_NAME           = "Sane C++ Libraries"
+PROJECT_NUMBER         = 
+PROJECT_BRIEF          = "C++ Platform Abstraction Libraries"
+PROJECT_LOGO           = SC.svg
+OUTPUT_DIRECTORY       = ../../_Build/_Documentation
+HTML_OUTPUT            = docs
+STRIP_FROM_PATH        = "$(STRIP_FROM_PATH)"
+ALWAYS_DETAILED_SEC    = YES
+FULL_PATH_NAMES        = NO
+JAVADOC_AUTOBRIEF      = YES
+DISTRIBUTE_GROUP_DOC   = YES
+SHOW_GROUPED_MEMB_INC  = YES
+SORT_GROUP_NAMES       = YES
+INPUT                  = ../../Documentation/Pages \
+                         ../../Documentation/Libraries \
+                         ../../Documentation/LibrariesExtra \
+                         ../../Libraries/Algorithms \
+                         ../../Libraries/Async \
+                         ../../Libraries/Build \
+                         ../../Libraries/Containers \
+                         ../../Libraries/File \
+                         ../../Libraries/FileSystem \
+                         ../../Libraries/FileSystemIterator \
+                         ../../Libraries/FileSystemWatcher \
+                         ../../Libraries/Foundation \
+                         ../../Libraries/Hashing \
+                         ../../Libraries/Http \
+                         ../../Libraries/Plugin \
+                         ../../Libraries/Process \
+                         ../../Libraries/Reflection \
+                         ../../Libraries/SerializationBinary \
+                         ../../LibrariesExtra/SerializationBinaryTypeErased \
+                         ../../Libraries/SerializationText \
+                         ../../Libraries/Socket \
+                         ../../Libraries/Strings \
+                         ../../Libraries/Testing \
+                         ../../Libraries/Threading \
+                         ../../Libraries/Time \
+                         ../../Bindings/c/sc_hashing
+EXAMPLE_PATH           = ../../
+FILE_PATTERNS          = *.h *.md
+RECURSIVE              = NO
+EXCLUDE_PATTERNS       = *Test.h \
+                         InitializerList.h
+PREDEFINED             = DOXYGEN
+EXCLUDE_SYMBOLS        = \
+TypeTraits::IsSame<*> \
+TypeTraits::AddReference<*> \
+TypeTraits::Conditional<*> \
+TypeTraits::EnableIf<*> \
+TypeTraits::IsConst<*> \
+TypeTraits::RemoveConst<*> \
+TypeTraits::RemovePointer<*> \
+TypeTraits::ReturnType<*> \
+TypeTraits::RemoveReference<*> \
+TypeTraits::IsLValueReference<*> \
+TypeTraits::IsRValueReference<*> \
+TypeTraits::TypeListGet<*> \
+Function<*> \
+TypeToEnum<*> \
+EnumToType<*> \
+Internal::* \
+PlacementNew \
+StringFormatterFor \
+StringFormat::Implementation \
+ExtendedTypeInfo<*> \
+Reflect<*> \
+IsPrimitive<*> \
+detail::* \
+Atomic<*> \
+VectorArrayVTable<*> \
+SegmentHeaderBase \
+SegmentItems  \
+SegmentOperations \
+VectorAllocator \
+ArrayAllocator \
+
+
+USE_MDFILE_AS_MAINPAGE = ../../Documentation/Pages/Index.md
+HTML_HEADER            = header.html
+HTML_EXTRA_STYLESHEET  = ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome.css \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-custom/custom.css \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome-sidebar-only.css \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome-sidebar-only-darkmode-toggle.css \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-custom/custom-alternative.css \
+                         SC.css
+HTML_EXTRA_FILES       = ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome-darkmode-toggle.js \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome-fragment-copy-button.js \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome-paragraph-link.js \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-custom/toggle-alternative-theme.js \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome-interactive-toc.js \
+                         ../../_Build/_Packages/doxygen-awesome-css_all/doxygen-awesome-tabs.js\
+                         favicon.png
+GENERATE_TREEVIEW      = YES
+GENERATE_LATEX         = NO
+ENUM_VALUES_PER_LINE   = 1
+COLLABORATION_GRAPH    = NO
+DOT_IMAGE_FORMAT       = svg
+WARN_IF_UNDOCUMENTED   = NO
+USE_PDFLATEX           = NO
diff --git a/Documentation/Doxygen/SC.css b/Documentation/Doxygen/SC.css
@@ -0,0 +1,26 @@
+tr.markdownTableRowOdd {
+    background-color: var(--odd-color);
+}
+table.markdownTable tr
+{
+    border-bottom: none;
+}
+
+table.markdownTable td, table.markdownTable th
+{
+    border: none;
+}
+
+table.markdownTable tbody
+{
+    border-radius: 0;
+    box-shadow: none;
+}
+th.markdownTableHeadLeft:first-child
+{
+    border-top-left-radius: 0;
+}
+th.markdownTableHeadLeft:last-child
+{
+    border-top-right-radius: 0;
+}
diff --git a/Documentation/Doxygen/SC.svg b/Documentation/Doxygen/SC.svg
diff --git a/Documentation/Doxygen/favicon.png b/Documentation/Doxygen/favicon.png
diff --git a/Documentation/Doxygen/header.html b/Documentation/Doxygen/header.html
@@ -0,0 +1,93 @@
+<!-- HTML header for doxygen 1.9.8-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=11"/>
+<meta name="generator" content="Doxygen $doxygenversion"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<script type="text/javascript">var page_layout=1;</script>
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+<script type="text/javascript" src="$relpath^jquery.js"></script>
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
+<script type="text/javascript" src="$relpath^toggle-alternative-theme.js"></script>
+<script type="text/javascript">
+    DoxygenAwesomeFragmentCopyButton.init()
+    DoxygenAwesomeDarkModeToggle.init()
+    DoxygenAwesomeParagraphLink.init()
+    DoxygenAwesomeInteractiveToc.init()
+    DoxygenAwesomeTabs.init()
+</script>
+$treeview
+$search
+$mathjax
+<!-- $darkmode -->
+<link rel="shortcut icon" href="$relpath^favicon.png">
+<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
+$extrastylesheet
+</head>
+<body>
+  <!-- https://tholman.com/github-corners/ -->
+<a href="https://github.com/pagghiu/SaneCppLibraries" class="github-corner" title="View source on GitHub" target="_blank">
+  <svg viewBox="0 0 250 250" width="40" height="40" style="position: absolute; top: 0; border: 0; right: 0; z-index: 99;" aria-hidden="true">
+  <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>
+
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr id="projectrow">
+  <!--BEGIN PROJECT_LOGO-->
+  <td id="projectlogo"><a href="index.html"><img alt="Logo" src="$relpath^$projectlogo" height="50px"/></a></td>
+  <!--END PROJECT_LOGO-->
+  <!--BEGIN PROJECT_NAME-->
+  <td id="projectalign">
+   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+   </div>
+   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+  </td>
+  <!--END PROJECT_NAME-->
+  <!--BEGIN !PROJECT_NAME-->
+   <!--BEGIN PROJECT_BRIEF-->
+    <td>
+    <div id="projectbrief">$projectbrief</div>
+    </td>
+   <!--END PROJECT_BRIEF-->
+  <!--END !PROJECT_NAME-->
+  <!--BEGIN DISABLE_INDEX-->
+   <!--BEGIN SEARCHENGINE-->
+     <!--BEGIN !FULL_SIDEBAR-->
+    <td>$searchbox</td>
+     <!--END !FULL_SIDEBAR-->
+   <!--END SEARCHENGINE-->
+  <!--END DISABLE_INDEX-->
+ </tr>
+  <!--BEGIN SEARCHENGINE-->
+   <!--BEGIN FULL_SIDEBAR-->
+   <tr><td colspan="2">$searchbox</td></tr>
+   <!--END FULL_SIDEBAR-->
+  <!--END SEARCHENGINE-->
+ </tbody>
+</table>
+</div>
+<!--END TITLEAREA-->
+<!-- end header part -->