Skip to content

Commit 630a350

Browse files
terrellnterrelln
committed
[contrib][doc] Setup documentation demo
1 parent aa6b355 commit 630a350

7 files changed

Lines changed: 317 additions & 0 deletions

File tree

‎.github/workflows/deploy-docs.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Simple workflow for deploying static content to GitHub Pages
2+
name: Deploy static content to Pages
3+
4+
on:
5+
# Runs on pushes targeting the default branch
6+
push:
7+
# TODO: Change this to dev
8+
branches: ["2025-01-20-mkdocs"]
9+
10+
# Allows you to run this workflow manually from the Actions tab
11+
workflow_dispatch:
12+
13+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
20+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
21+
concurrency:
22+
group: "pages"
23+
cancel-in-progress: false
24+
25+
jobs:
26+
build:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
with:
32+
submodules: recursive
33+
- name: Setup build environment
34+
run: |
35+
sudo apt-get update
36+
sudo apt-get install doxygen clang-format
37+
pip install mkdocs-material==9.5.50 mkdocstrings==0.27.0 mkdocs-autorefs==1.3.0
38+
- name: build
39+
run: |
40+
./contrib/doc/mkdocs.py build
41+
42+
43+
deploy:
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
runs-on: ubuntu-latest
48+
needs: build
49+
steps:
50+
- name: Checkout
51+
uses: actions/checkout@v4
52+
- name: Setup Pages
53+
uses: actions/configure-pages@v5
54+
- name: Upload artifact
55+
uses: actions/upload-pages-artifact@v3
56+
with:
57+
# Upload the built site
58+
path: './build-doc/site/'
59+
- name: Deploy to GitHub Pages
60+
id: deployment
61+
uses: actions/deploy-pages@v4

‎contrib/doc/mkdocs.py‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
#!/usr/bin/env python3
2+
# A script to invoke mkdocs with the correct environment.
3+
# Additionally supports deploying via mike:
4+
# ./mkdocs deploy
5+
6+
import errno
7+
import os
8+
import shutil
9+
import sys
10+
from pathlib import Path
11+
from subprocess import call
12+
13+
contrib_doc_dir = Path(__file__).parent
14+
root_dir = contrib_doc_dir.parents[1]
15+
zstd_handler_dir = contrib_doc_dir / "mkdocstrings-zstd" / "src"
16+
config_path = os.path.join(contrib_doc_dir, "mkdocs.yml")
17+
18+
19+
build_dir = root_dir / "build-docs"
20+
21+
# Set PYTHONPATH for the mkdocstrings handler.
22+
env = os.environ.copy()
23+
path = env.get("PYTHONPATH")
24+
env["PYTHONPATH"] = (path + ":" if path else "") + str(zstd_handler_dir)
25+
26+
# redirect_page = \
27+
# '''<!DOCTYPE html>
28+
# <html>
29+
# <head>
30+
# <meta charset="utf-8">
31+
# <title>Redirecting</title>
32+
# <noscript>
33+
# <meta http-equiv="refresh" content="1; url=11.0/" />
34+
# </noscript>
35+
# <script>
36+
# window.location.replace(
37+
# "api/" + window.location.search + window.location.hash
38+
# );
39+
# </script>
40+
# </head>
41+
# <body>
42+
# Redirecting to <a href="api/">api</a>...
43+
# </body>
44+
# </html>
45+
# '''
46+
47+
args = sys.argv[1:]
48+
if len(args) > 0:
49+
command = args[0]
50+
if command == "deploy":
51+
git_url = "https://github.com/" if "CI" in os.environ else "git@github.com:"
52+
site_repo = git_url + "fmtlib/fmt.dev.git"
53+
54+
site_dir = os.path.join(build_dir, "fmt.dev")
55+
try:
56+
shutil.rmtree(site_dir)
57+
except OSError as e:
58+
if e.errno == errno.ENOENT:
59+
pass
60+
ret = call(["git", "clone", "--depth=1", site_repo, site_dir])
61+
if ret != 0:
62+
sys.exit(ret)
63+
64+
# Copy the config to the build dir because the site is built relative to it.
65+
config_build_path = os.path.join(build_dir, "mkdocs.yml")
66+
shutil.copyfile(config_path, config_build_path)
67+
68+
version = args[1]
69+
ret = call(
70+
["mike"]
71+
+ args
72+
+ ["--config-file", config_build_path, "--branch", "master"],
73+
cwd=site_dir,
74+
env=env,
75+
)
76+
if ret != 0 or version == "dev":
77+
sys.exit(ret)
78+
redirect_page_path = os.path.join(site_dir, version, "api.html")
79+
with open(redirect_page_path, "w") as file:
80+
file.write(redirect_page)
81+
ret = call(["git", "add", redirect_page_path], cwd=site_dir)
82+
if ret != 0:
83+
sys.exit(ret)
84+
ret = call(["git", "commit", "--amend", "--no-edit"], cwd=site_dir)
85+
sys.exit(ret)
86+
elif not command.startswith("-"):
87+
args += ["-f", config_path]
88+
sys.exit(call(["mkdocs"] + args, env=env))

‎contrib/doc/mkdocs.yml‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
site_name: 'Zstandard'
2+
3+
docs_dir: ../../doc
4+
5+
site_dir: ../../build-docs/site
6+
7+
repo_url: https://github.com/facebook/zstd
8+
9+
extra_css:
10+
- zstd.css
11+
12+
nav:
13+
- Home: index.md
14+
- User Guide:
15+
- Basics: user-guide/basics.md
16+
- Simple: user-guide/simple.md
17+
- Advanced: user-guide/advanced.md
18+
19+
theme:
20+
name: material
21+
logo: images/zstd_logo86.png
22+
favicon: images/zstd_logo86.png
23+
features:
24+
- search.suggest
25+
- navigation.tabs
26+
- navigation.top
27+
# - toc.integrate
28+
29+
palette:
30+
# Palette toggle for automatic mode
31+
- media: "(prefers-color-scheme)"
32+
toggle:
33+
icon: material/brightness-auto
34+
name: Switch to light mode
35+
36+
# Palette toggle for light mode
37+
- media: "(prefers-color-scheme: light)"
38+
scheme: default
39+
toggle:
40+
icon: material/brightness-7
41+
name: Switch to dark mode
42+
43+
# Palette toggle for dark mode
44+
- media: "(prefers-color-scheme: dark)"
45+
scheme: slate
46+
toggle:
47+
icon: material/brightness-4
48+
name: Switch to system preference
49+
50+
markdown_extensions:
51+
- admonition
52+
- pymdownx.details
53+
- md_in_html
54+
- pymdownx.highlight:
55+
use_pygments: true
56+
anchor_linenums: true
57+
line_spans: __span
58+
pygments_lang_class: true
59+
- pymdownx.inlinehilite
60+
- pymdownx.snippets
61+
- pymdownx.superfences:
62+
custom_fences:
63+
- name: mermaid
64+
class: mermaid
65+
format: !!python/name:pymdownx.superfences.fence_code_format
66+
67+
plugins:
68+
- search
69+
- mkdocstrings:
70+
default_handler: zstd
71+
handlers:
72+
zstd:
73+
source_directory: "../../lib/"
74+
build_directory: "../../build-docs/"
75+
sources: [
76+
"zstd.h",
77+
"zstd_errors.h",
78+
]
79+
predefined:
80+
- ZSTD_STATIC_LINKING_ONLY
81+
options:
82+
clang_format_based_on_style: "Google"
83+
heading_level: 3
84+
85+
# exclude_docs: ChangeLog-old.md
86+
87+
extra:
88+
generator: false
89+
# version:
90+
# provider: mike

‎doc/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Under Construction

‎doc/user-guide/advanced.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
::: ZSTD_compress2
2+
3+
::: ZSTD_decompressDCtx
4+
5+
::: ZSTD_findDecompressedSize

‎doc/user-guide/basics.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Basics
3+
---
4+
These are the basic helper functions that you need to interact with `zstd`.
5+
6+
## Error Checking
7+
8+
Any function that returns a `size_t` must be checked with `ZSTD_isError()`.
9+
10+
::: ZSTD_isError
11+
12+
If the function returned an error, then `ZSTD_getErrorName()` will return the error string.
13+
14+
::: ZSTD_getErrorName
15+
16+
## Compression Utilities
17+
18+
`ZSTD_compressBound()` returns the maximum possible compressed size of a given
19+
input, which will be slightly larger than the input size. If you provide an
20+
output buffer at least this large to [ZSTD_compress()][ZSTD_compress],
21+
[ZSTD_compressCCtx()][ZSTD_compressCCtx], or [ZSTD_compress2()][ZSTD_compress2]
22+
the compressed result is guaranteed to fit.
23+
24+
::: ZSTD_compressBound
25+
26+
## Decompression Utilities
27+
28+
`ZSTD_getFrameContentSize()` will return the (decompressed) content size of a
29+
Zstandard or Skippable frame. If the content size is not known it will return
30+
[ZSTD_CONTENTSIZE_UNKNOWN][], and if an error occurs it will return
31+
[ZSTD_CONTENTSIZE_ERROR][].
32+
33+
???+ warning
34+
35+
This only returns the content size of the first compressed frame in the
36+
compressed source. Zstd decompression functions like
37+
[ZSTD_decompress()][ZSTD_decompress] will decompress zero or more
38+
concatenated frames. So calling this function does not guarantee that
39+
decompression will have enough space, unless you know a-priori that there
40+
is only one compressed frame in the source.
41+
42+
::: ZSTD_getFrameContentSize
43+
44+
::: ZSTD_CONTENTSIZE_UNKNOWN
45+
options:
46+
show_description: false
47+
48+
::: ZSTD_CONTENTSIZE_ERROR
49+
options:
50+
show_description: false
51+
52+
`ZSTD_findFrameCompressedSize()` will return the compressed size of the Zstd
53+
frame. This function can be useful if:
54+
55+
- You don't know the compressed size of the frame.
56+
- There may be more than one compressed frame in the compressed source.
57+
58+
???+ note
59+
60+
This function has to traverse the entire Zstd compressed frame, and read
61+
each block's header. It is cheap, given that there is normally one block
62+
for every 128 KiB of content, but it isn't free.
63+
64+
::: ZSTD_findFrameCompressedSize

‎doc/user-guide/simple.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
::: ZSTD_compress
3+
4+
::: ZSTD_decompress
5+
6+
::: ZSTD_compressCCtx
7+
8+
::: ZSTD_decompressDCtx

0 commit comments

Comments
 (0)