[contrib][doc] Setup documentation demo

Author: terrelln

.github/workflows/deploy-docs.yml

@@ -0,0 +1,58 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    # TODO: Change this to dev
+    branches: ["2025-01-20-mkdocs"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Setup build environment
+        run: |
+            sudo apt-get update
+            sudo apt-get install doxygen clang-format
+            pip install mkdocs-material==9.5.50 mkdocstrings==0.27.0 mkdocs-autorefs==1.3.0
+      - name: build
+        run: |
+            ./contrib/doc/mkdocs.py build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './build-docs/site/'
+
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

contrib/doc/mkdocs.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# A script to invoke mkdocs with the correct environment.
+# Additionally supports deploying via mike:
+#   ./mkdocs deploy
+
+import errno
+import os
+import shutil
+import sys
+from pathlib import Path
+from subprocess import call
+
+contrib_doc_dir = Path(__file__).parent
+root_dir = contrib_doc_dir.parents[1]
+zstd_handler_dir = contrib_doc_dir / "mkdocstrings-zstd" / "src"
+config_path = os.path.join(contrib_doc_dir, "mkdocs.yml")
+
+
+build_dir = root_dir / "build-docs"
+
+# Set PYTHONPATH for the mkdocstrings handler.
+env = os.environ.copy()
+path = env.get("PYTHONPATH")
+env["PYTHONPATH"] = (path + ":" if path else "") + str(zstd_handler_dir)
+
+args = sys.argv[1:]
+args += ["-f", config_path]
+sys.exit(call(["mkdocs"] + args, env=env))

contrib/doc/mkdocs.yml

@@ -0,0 +1,90 @@
+site_name: 'Zstandard'
+
+docs_dir: ../../doc
+
+site_dir: ../../build-docs/site
+
+repo_url: https://github.com/facebook/zstd
+
+extra_css:
+  - zstd.css
+
+nav:
+  - Home: index.md
+  - User Guide:
+    - Basics: user-guide/basics.md
+    - Simple: user-guide/simple.md
+    - Advanced: user-guide/advanced.md
+
+theme:
+  name: material
+  logo: images/zstd_logo86.png
+  favicon: images/zstd_logo86.png
+  features:
+    - search.suggest
+    - navigation.tabs
+    - navigation.top
+    # - toc.integrate
+  
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default 
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - md_in_html
+  - pymdownx.highlight:
+      use_pygments: true
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: zstd
+      handlers:
+        zstd:
+          source_directory: "../../lib/"
+          build_directory: "../../build-docs/"
+          sources: [
+            "zstd.h",
+            "zstd_errors.h",
+          ]
+          predefined:
+            - ZSTD_STATIC_LINKING_ONLY
+          options:
+            clang_format_based_on_style: "Google"
+            heading_level: 3
+
+# exclude_docs: ChangeLog-old.md
+
+extra:
+  generator: false
+#   version:
+#     provider: mike

contrib/doc/mkdocstrings-zstd

@@ -0,0 +1 @@
+# Under Construction

doc/index.md

@@ -0,0 +1,35 @@
+## Compression Context
+
+Context lifteimte management
+
+::: ZSTD_createCCtx
+
+::: ZSTD_freeCCtx
+
+## Configure Compression
+
+Configure any parameters you like
+
+::: ZSTD_CCtx_setParameter
+
+::: ZSTD_cParameter
+
+## Dictionary Compression
+
+Load dictionaries
+
+::: ZSTD_CCtx_loadDictionary
+
+## Single shot compression
+
+Then compress
+
+::: ZSTD_compress2
+
+## Streaming compression
+
+You can also use streaming compression
+
+::: ZSTD_compressStream2
+
+::: ZSTD_EndDirective

doc/user-guide/advanced.md

@@ -0,0 +1,64 @@
+---
+title: Basics
+---
+These are the basic helper functions that you need to interact with `zstd`.
+
+## Error Checking
+
+Any function that returns a `size_t` must be checked with `ZSTD_isError()`.
+
+::: ZSTD_isError
+
+If the function returned an error, then `ZSTD_getErrorName()` will return the error string.
+
+::: ZSTD_getErrorName
+
+## Compression Utilities
+
+`ZSTD_compressBound()` returns the maximum possible compressed size of a given
+input, which will be slightly larger than the input size. If you provide an
+output buffer at least this large to [ZSTD_compress()][ZSTD_compress],
+[ZSTD_compressCCtx()][ZSTD_compressCCtx], or [ZSTD_compress2()][ZSTD_compress2]
+the compressed result is guaranteed to fit.
+
+::: ZSTD_compressBound
+
+## Decompression Utilities
+
+`ZSTD_getFrameContentSize()` will return the (decompressed) content size of a
+Zstandard or Skippable frame. If the content size is not known it will return
+[ZSTD_CONTENTSIZE_UNKNOWN][], and if an error occurs it will return
+[ZSTD_CONTENTSIZE_ERROR][].
+
+???+ warning 
+
+    This only returns the content size of the first compressed frame in the
+    compressed source. Zstd decompression functions like
+    [ZSTD_decompress()][ZSTD_decompress] will decompress zero or more
+    concatenated frames. So calling this function does not guarantee that
+    decompression will have enough space, unless you know a-priori that there
+    is only one compressed frame in the source.
+
+::: ZSTD_getFrameContentSize
+
+::: ZSTD_CONTENTSIZE_UNKNOWN
+    options:
+        show_description: false
+
+::: ZSTD_CONTENTSIZE_ERROR
+    options:
+        show_description: false
+
+`ZSTD_findFrameCompressedSize()` will return the compressed size of the Zstd
+frame. This function can be useful if:
+
+- You don't know the compressed size of the frame.
+- There may be more than one compressed frame in the compressed source.
+
+???+ note
+
+    This function has to traverse the entire Zstd compressed frame, and read
+    each block's header. It is cheap, given that there is normally one block
+    for every 128 KiB of content, but it isn't free.
+
+::: ZSTD_findFrameCompressedSize

doc/user-guide/basics.md

@@ -0,0 +1,8 @@
+
+::: ZSTD_compress
+
+::: ZSTD_decompress
+
+::: ZSTD_compressCCtx
+
+::: ZSTD_decompressDCtx