Add GitHub Pages documentation site (issue 12)

.github/workflows/deploy-docs.yml

@@ -0,0 +1,74 @@
+name: Deploy Documentation (GitHub Pages)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    name: Build the documentation site and deploy to GitHub Pages
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # The full history is required to compute the
+          # 1.0.<commit-count>.<short-sha> project version.
+          fetch-depth: 0
+
+      - name: Install Doxygen
+        uses: ssciwr/doxygen-install@v2.0.3
+        with:
+          # The latest stable release the documentation was generated and
+          # validated with.
+          version: 1.18.0
+
+      - name: Install Graphviz
+        uses: ts-graphviz/setup-graphviz@v2.0.2
+
+      - name: Generate the Doxygen configuration file
+        run: |
+          PROJECT_VERSION="1.0.$(git rev-list --count HEAD).$(git rev-parse --short HEAD)"
+          # The version placeholder is the only build-time substitution;
+          # the HTML output goes to docs/api/ (OUTPUT_DIRECTORY +
+          # HTML_OUTPUT, see doxygen.conf.in), so the MkDocs build serves
+          # it as the /api/ section of the site.
+          sed -e "s|@OPENSIMPLEX2_VERSION@|${PROJECT_VERSION}|" \
+              doxygen.conf.in > doxygen.conf
+          grep -E '^(PROJECT_NAME|PROJECT_NUMBER)' doxygen.conf
+
+      - name: Generate the Doxygen HTML documentation
+        run: doxygen doxygen.conf
+
+      - name: Copy the README and the LICENSE as the site home page assets
+        run: |
+          # docs/index.md is generated from the root README.md at build
+          # time (it is gitignored), so the README stays the single
+          # source of truth for the site home page. The LICENSE file is
+          # copied too, because the README links it relatively and
+          # `mkdocs build --strict` fails on unresolved relative links.
+          mkdir -p docs
+          cp README.md docs/index.md
+          cp LICENSE docs/
+
+      - name: Install MkDocs and the Material theme
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs==1.6.1 mkdocs-material==9.7.7
+
+      - name: Build the documentation site
+        run: |
+          mkdocs build --strict
+          ls -la site site/api | head -40
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: site
+          clean: true

.gitignore

@@ -13,3 +13,11 @@ cmake_install.cmake
 
 # Runtime test deployment dir (created by the QuasarApp CMake test targets)
 Testing
+
+# Documentation site build artifacts
+# (generated by .github/workflows/deploy-docs.yml, not committed)
+doxygen.conf
+docs/index.md
+docs/LICENSE
+docs/api/
+site/

docs/overrides/main.css

@@ -0,0 +1,43 @@
+/*
+ * main.css
+ *
+ * Custom stylesheet for the MkDocs Material site, attached through the
+ * top-level extra_css option (see mkdocs.yml) and therefore loaded after
+ * the theme's main.css and palette.css, so every rule in this file wins
+ * the cascade.
+ *
+ * Material for MkDocs only ships prebuilt palette rules for the named
+ * Material colors, so the teal brand palette (intentionally different
+ * from the upstream documentation theme) is applied here by overriding
+ * the theme's CSS custom properties per color scheme:
+ *
+ *   primary        #0e6b64 (deep teal: top bar, active nav, tabs)
+ *   primary dark   #0a4f4a (pressed / dark variant of the primary bar)
+ *   primary light  #17857c (hover / light variant of the primary bar)
+ *   accent         #0d7d70 (light-scheme links, ~5.0:1 contrast on white)
+ *   accent light   #6fd0c2 (dark-scheme links, contrast on the slate bg)
+ */
+
+/* primary: deep teal (both schemes) */
+[data-md-color-scheme="default"],
+[data-md-color-scheme="slate"] {
+    --md-primary-fg-color: #0e6b64;
+    --md-primary-fg-color--light: #17857c;
+    --md-primary-fg-color--dark: #0a4f4a;
+}
+
+/* accent: teal on the light scheme (also colors the in-text links, since
+   Material 9 derives --md-typeset-a-color from the primary color by
+   default) */
+[data-md-color-scheme="default"] {
+    --md-accent-fg-color: #0d7d70;
+    --md-accent-fg-color--transparent: #0d7d701a;
+    --md-typeset-a-color: #0d7d70;
+}
+
+/* accent: light teal on the dark (slate) scheme */
+[data-md-color-scheme="slate"] {
+    --md-accent-fg-color: #6fd0c2;
+    --md-accent-fg-color--transparent: #6fd0c21a;
+    --md-typeset-a-color: #6fd0c2;
+}

doxygen.conf.in

@@ -0,0 +1,104 @@
+#
+# doxygen.conf.in
+#
+# Doxygen configuration template for the OpenSimplex2 documentation site.
+#
+# The "Deploy Documentation (GitHub Pages)" workflow substitutes the
+# @OPENSIMPLEX2_VERSION@ placeholder with "1.0.<commit-count>.<short-sha>"
+# and runs `doxygen doxygen.conf` from the repository root
+# (see .github/workflows/deploy-docs.yml). The HTML output is written to
+# docs/api/ (OUTPUT_DIRECTORY + HTML_OUTPUT) and served as the /api/
+# section of the MkDocs site (see mkdocs.yml).
+#
+# res/doxygen-material.css is copied into the output directory by Doxygen
+# (HTML_EXTRA_STYLESHEET) and restyles the generated pages with the site's
+# teal palette.
+
+# ------------------------------------------------------------------------
+# Project related configuration options
+# ------------------------------------------------------------------------
+
+DOXYFILE_ENCODING      = UTF-8
+
+PROJECT_NAME           = OpenSimplex2
+
+# Substituted at build time, see the file header.
+PROJECT_NUMBER         = @OPENSIMPLEX2_VERSION@
+
+PROJECT_BRIEF          = "The most fast implementation of the OpenSimplex noise (2D, 3D and 4D) in C"
+
+OUTPUT_DIRECTORY       = docs
+
+CREATE_SUBDIRS         = NO
+
+USE_MDFILES            = NO
+
+INPUT                  = OpenSimplex2F.h \
+                         OpenSimplex2F.c
+
+FILE_PATTERNS          = *.h \
+                         *.c
+
+RECURSIVE              = NO
+
+OUTPUT_LANGUAGE        = English
+
+# ------------------------------------------------------------------------
+# Build related configuration options
+# ------------------------------------------------------------------------
+
+EXTRACT_ALL            = YES
+
+EXTRACT_STATIC         = NO
+
+EXTRACT_PACKAGE        = NO
+
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+TYPEDEF_HIDES_STRUCT   = YES
+
+BRIEF_MEMBER_DESC      = YES
+
+QTLIKE_AUTOBRIEF       = YES
+
+JAVADOC_AUTOBRIEF      = YES
+
+QUIET                  = NO
+
+WARN_IF_UNDOCUMENTED   = YES
+
+WARN_AS_ERROR          = NO
+
+# ------------------------------------------------------------------------
+# Output related configuration options
+# ------------------------------------------------------------------------
+
+GENERATE_HTML          = YES
+
+# The generated pages are written to docs/api/ so that the MkDocs build
+# serves them as the /api/ section of the site.
+HTML_OUTPUT            = api
+
+GENERATE_TREEVIEW      = YES
+
+GENERATE_HTMLHELP      = NO
+
+GENERATE_LATEX         = NO
+
+GENERATE_XML           = NO
+
+# Copied into the output directory and loaded after the generated
+# doxygen.css, so it wins the cascade (see the file itself for details).
+HTML_EXTRA_STYLESHEET  = res/doxygen-material.css
+
+# ------------------------------------------------------------------------
+# Dot related configuration options
+# ------------------------------------------------------------------------
+
+HAVE_DOT               = YES
+
+CALL_GRAPH             = YES
+
+CALLER_GRAPH           = YES
+
+MAX_DOT_GRAPH_DEPTH    = 0

mkdocs.yml

@@ -0,0 +1,84 @@
+# OpenSimplex2 documentation site (GitHub Pages)
+#
+# Built with MkDocs + the Material theme. Before `mkdocs build` runs,
+# the "Deploy Documentation (GitHub Pages)" workflow copies the root
+# README.md to docs/index.md (the site home page) and generates the
+# Doxygen HTML output into docs/api/, so the API section of the site
+# is served from /api/.
+
+site_name: OpenSimplex2
+site_description: The most fast implementation of the OpenSimplex noise (2D, 3D and 4D) in C
+site_url: https://quasarapp.github.io/OpenSimplex2/
+
+repo_name: QuasarApp/OpenSimplex2
+repo_url: https://github.com/QuasarApp/OpenSimplex2
+edit_uri: https://github.com/QuasarApp/OpenSimplex2/edit/main/
+
+docs_dir: docs
+site_dir: site
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      # Teal brand palette (intentionally different from the upstream
+      # documentation theme). These entries set the data-md-color-* page
+      # attributes (scheme switching / persistence), but Material ships
+      # no prebuilt rules for custom hex values, so the actual CSS
+      # variable overrides live in docs/overrides/main.css (attached via
+      # extra_css). Deep teal (#0e6b64) top bar, teal (#0d7d70) links.
+      primary: "#0e6b64"
+      accent: "#0d7d70"
+      toggle:
+        icon: material/brightness-4
+        name: Switch to dark mode
+    - scheme: slate
+      # Same teal top bar on the slate neutrals, light teal (#6fd0c2)
+      # links for contrast on the dark background.
+      primary: "#0e6b64"
+      accent: "#6fd0c2"
+      toggle:
+        icon: material/brightness-7
+        name: Switch to light mode
+  font:
+    text: Roboto
+    code: Roboto Mono
+  features:
+    - content.code.copy
+    - navigation.footer
+    - navigation.indexes
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.suggest
+    - toc
+
+# Material for MkDocs only ships prebuilt palette rules for the named
+# Material colors, so the teal palette is applied through this extra
+# stylesheet (loaded after the theme CSS, see the file header in
+# docs/overrides/main.css for the color choices).
+extra_css:
+  - overrides/main.css
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+
+nav:
+  # index.md is copied from the root README.md by the documentation
+  # workflow before the MkDocs build, so the README stays the single
+  # source of truth and the generated copy is not committed.
+  - Home: index.md
+  # api/index.html is the static Doxygen index generated into docs/api/
+  # by the documentation workflow before the MkDocs build.
+  - API: api/index.html