shadowsocks · madeye · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -43,7 +43,7 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libpcre2-dev libmbedtls-dev libsodium-dev libuv1-dev libc-ares-dev
           sudo apt-get install -y --no-install-recommends \
-            build-essential cmake debhelper dpkg-dev fakeroot asciidoc-base xmlto pkg-config
+            build-essential cmake debhelper dpkg-dev fakeroot doxygen pkg-config
 
       - name: Debian package build test
         run: bash tests/test_deb_build.sh

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -0,0 +1,63 @@
+name: documentation
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: documentation-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install Doxygen
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends doxygen
+      - name: Build and validate documentation
+        run: |
+          python3 scripts/check_cli_docs.py
+          python3 -m unittest discover -s tests -p test_cli_docs.py
+          cmake -S . -B build-docs -DWITH_DOC_MAN=ON -DWITH_DOC_HTML=ON
+          cmake --build build-docs --target doc-man doc-html --parallel 2
+          python3 scripts/check_cli_docs.py --rendered build-docs
+          test -s build-docs/html/index.html
+      - name: Package downloadable man pages
+        run: |
+          tar -czf build-docs/html/man-pages.tar.gz -C build-docs \
+            man/ss-local.1 man/ss-server.1 man/ss-tunnel.1 man/ss-redir.1 \
+            man/ss-manager.1 man/ss-nat.1 man/shadowsocks-c.8 man/shadowsocks-libev.8
+          tar -tzf build-docs/html/man-pages.tar.gz
+      - name: Upload GitHub Pages site
+        if: github.repository == 'shadowsocks/shadowsocks-c' && github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: build-docs/html
+
+  deploy:
+    needs: docs
+    if: github.repository == 'shadowsocks/shadowsocks-c' && github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+      - name: Deploy documentation
+        id: deployment
+        uses: actions/deploy-pages@v5
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -26,27 +26,10 @@ jobs:
         run: actionlint -shellcheck= -pyflakes=
       - name: Lint Python scripts and tests
         run: ruff check --select E9,F63,F7,F82 tests scripts
-      - name: Check generated CLI documentation
+      - name: Check Doxygen CLI documentation
         run: |
-          python3 scripts/gen_cli_docs.py --check
-          python3 -m unittest discover -s tests -p test_gen_cli_docs.py
-
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Install documentation tools
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends asciidoc xmlto docbook-xml docbook-xsl
-      - name: Build man pages and HTML from source
-        run: |
-          cmake -S . -B build-docs -DWITH_DOC_MAN=ON -DWITH_DOC_HTML=ON
-          cmake --build build-docs --target doc-man doc-html --parallel 2
-          test -s build-docs/man/ss-local.1
-          test -s build-docs/man/ss-nat.1
-          test -s build-docs/man/shadowsocks-c.8
-          test -s build-docs/html/ss-local.html
+          python3 scripts/check_cli_docs.py
+          python3 -m unittest discover -s tests -p test_cli_docs.py
 
   tests:
     strategy:

diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md
@@ -75,35 +75,39 @@ notices.
 
 ## CLI and manual documentation
 
-The SYNOPSIS and OPTIONS sections of the manual pages are generated from the
-literal `getopt_long` declarations in `src/{local,server,tunnel,redir,manager}.c`
-and the `getopts` declaration in `src/ss-nat`. Descriptions and argument names live
-in `CLI_DOC` source comments: common C options in `src/utils.c`, program-specific
-overrides in the corresponding C file, and shell options in `src/ss-nat`.
-Each entry has an AsciiDoc term such as `--mtu <MTU>::` followed by its description.
-The generator checks option coverage and argument arity across platform variants;
-describe platform or feature restrictions in the comment. Cipher lists come from
-the C cipher tables. Keep explanatory sections and examples in `doc/*.asciidoc`.
-
-After changing a parser or its documentation comments, regenerate the checked-in
-pages and run the generator tests:
+Doxygen 1.9.4 or newer renders HTML and man pages directly from native source
+snippets. Each CLI parser has a `cli-options` snippet containing Doxygen
+`\snippet{doc}` references to its option descriptions. Shared descriptions live
+in `src/utils.c`; command-specific descriptions live beside the parser. The
+`ss-nat` script keeps its snippets in a quoted no-op heredoc so documentation
+cannot execute shell substitutions. Cipher tables are included directly with
+Doxygen code snippets.
+
+When adding or changing an option, update its parser, source snippet, and the
+parser's `cli-options` list. Keep argument names and platform restrictions in the
+source description. Edit narrative sections and examples in `doc/*.md`. There
+are no generated documentation files to commit.
+
+Check that documented flags and argument arity match every platform variant:
 
 ```sh
-python3 scripts/gen_cli_docs.py
-python3 scripts/gen_cli_docs.py --check
-python3 -m unittest discover -s tests -p test_gen_cli_docs.py
+python3 scripts/check_cli_docs.py
+python3 -m unittest discover -s tests -p test_cli_docs.py
 ```
 
-To render the manuals, install Python 3, AsciiDoc, and xmlto, then run:
+Install Doxygen, then render both formats:
 
 ```sh
 cmake -S . -B build-docs -DWITH_DOC_MAN=ON -DWITH_DOC_HTML=ON
 cmake --build build-docs --target doc-man doc-html --parallel
+python3 scripts/check_cli_docs.py --rendered build-docs
 ```
 
-The build generates pages in the build directory without modifying source files
-or executing target binaries, so it also works when cross-compiling. CI checks
-that committed pages are current and renders both man and HTML output.
+Open `build-docs/html/index.html` for the CLI reference. Man pages are written to
+`build-docs/man/`, retaining the six command names and the `shadowsocks-c(8)` and
+`shadowsocks-libev(8)` overview lookups. Builds read source snippets without
+executing target binaries, including when cross-compiling. Python is needed only
+for validation; Doxygen alone renders the documentation.
 
 ## Pull requests
 
@@ -114,3 +118,13 @@ requests and exclude generated build output, credentials, and local configuratio
 
 Respond to review feedback and keep the branch current with `master`. Maintainers
 will review the implementation and relevant CI results before merging.
+
+## Published documentation
+
+The `documentation` workflow builds and validates Doxygen output on pull requests.
+After a push to `master`, it publishes `build-docs/html` through GitHub Pages using
+GitHub Actions, including a downloadable `man-pages.tar.gz` archive. You can also
+run the workflow manually on `master` to redeploy.
+Deployment is limited to the canonical repository's `master` branch; pull requests
+and forks only validate the documentation. The `github-pages` environment records
+the deployed site URL and deployment history.
diff --git a/README.md b/README.md
@@ -13,6 +13,9 @@ created by [@clowwindy](https://github.com/clowwindy), and maintained by
 
 Current version: 3.3.6 | [Changelog](debian/changelog)
 
+[CLI reference and configuration guide](https://shadowsocks.github.io/shadowsocks-c/)
+are generated from the source with Doxygen and published after updates to `master`.
+
 ## Community
 
 See the [contribution guide](CONTRIBUTION.md) for development setup, testing,
@@ -145,7 +148,7 @@ client mode and build options. Existing Snap packages still use the
 The default build uses pinned sources included in this repository. It needs a
 C11 compiler, CMake 3.20+, and Make or Ninja. No Git submodules, dependency
 package installations, or network access are needed for configuration/build.
-Python is used by integration tests and optional documentation generation.
+Python is used by tests; optional documentation builds require Doxygen 1.9.4+.
 
 ```sh
 cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
@@ -157,9 +160,8 @@ cmake --install build --prefix /your/install/prefix
 Programs are in `build/bin/`. Bundled binaries link to platform runtime
 libraries; they do not require separately installed third-party libraries.
 
-Man pages and HTML documentation derive their CLI sections from the source
-option parsers. See [the documentation workflow](CONTRIBUTION.md#cli-and-manual-documentation)
-for regeneration and rendering commands.
+Doxygen renders man pages and HTML documentation from CLI source comments. See [the documentation workflow](CONTRIBUTION.md#cli-and-manual-documentation)
+for validation and rendering commands.
 
 For a smaller build, use `-DSS_MINIMAL=ON`. It excludes PCRE2 regex, plugin
 subprocesses, the manager, and legacy stream ciphers. Minimal ACLs support
@@ -180,7 +182,7 @@ Use `-DCMAKE_PREFIX_PATH=/opt/homebrew/opt/mbedtls@3` when needed on macOS.
 | `SS_BUILD_SHARED_LIBRARY` | `ON` | Shared embedding library |
 | `SS_MINIMAL` | `OFF` | Disable regex, plugins, manager, and legacy stream ciphers |
 | `SS_ENABLE_REGEX` / `SS_ENABLE_PLUGINS` / `SS_ENABLE_LEGACY` | `ON` | Individual compatibility features |
-| `WITH_DOC_MAN` / `WITH_DOC_HTML` | `OFF` | Generate documentation (requires asciidoc; man pages also need xmlto) |
+| `WITH_DOC_MAN` / `WITH_DOC_HTML` | `OFF` | Generate documentation (requires Doxygen 1.9.4+) |
 | `SS_INSTALL_TOOLS` | `OFF` | Install platform shell helpers |
 | `ENABLE_SANITIZERS` | `OFF` | AddressSanitizer and UndefinedBehaviorSanitizer |
 | `ENABLE_CONNMARKTOS` / `ENABLE_NFTABLES` | `OFF` | Optional Linux firewall integrations |
@@ -273,7 +275,7 @@ sudo cmake --install build
 
 Distribution packagers can install `libpcre2-dev libuv1-dev libc-ares-dev
 libmbedtls-dev libsodium-dev` and select `-DSS_DEPENDENCY_MODE=system
--DWITH_STATIC=OFF`. Documentation additionally needs asciidoc and xmlto.
+-DWITH_STATIC=OFF`. Documentation additionally needs Doxygen 1.9.4 or newer.
 
 ### FreeBSD
 #### Install

diff --git a/README_pt_BR.md b/README_pt_BR.md
@@ -173,7 +173,7 @@ Se você estiver usando o CentOS 7, precisará instalar estes pré-requisitos pa
 
 ```bash
 yum install epel-release -y
-yum install gcc gettext autoconf libtool automake make pcre-devel asciidoc xmlto c-ares-devel libev-devel libsodium-devel mbedtls-devel -y
+yum install gcc gettext autoconf libtool automake make pcre-devel doxygen c-ares-devel libev-devel libsodium-devel mbedtls-devel -y
 ```
 
 ### Archlinux & Manjaro
@@ -208,8 +208,7 @@ Em geral, você precisa das seguintes dependências de compilação:
 * libpcre3 (antiga biblioteca pcre)
 * libev
 * libc-ares
-* asciidoc (somente para documentação)
-* xmlto (apenas para documentação)
+* Doxygen 1.9.4+ (somente para documentação)
 
 Notas: Fedora 26 libsodium versão >= 1.0.12, então você pode instalar via dnf install libsodium em vez de compilar a partir da fonte.
 
@@ -222,11 +221,11 @@ Para algumas das distribuições, você pode instalar dependências de compilaç
 ```bash
 # Instalação de dependências básicas de compilação
 ## Debian / Ubuntu
-sudo apt-get install --no-install-recommends gettext build-essential autoconf libtool libpcre3-dev asciidoc xmlto libev-dev libc-ares-dev automake libmbedtls-dev libsodium-dev pkg-config
+sudo apt-get install --no-install-recommends gettext build-essential autoconf libtool libpcre3-dev doxygen libev-dev libc-ares-dev automake libmbedtls-dev libsodium-dev pkg-config
 ## CentOS / Fedora / RHEL
-sudo yum install gettext gcc autoconf libtool automake make asciidoc xmlto c-ares-devel libev-devel
+sudo yum install gettext gcc autoconf libtool automake make doxygen c-ares-devel libev-devel
 ## Arch
-sudo pacman -S gettext gcc autoconf libtool automake make asciidoc xmlto c-ares libev
+sudo pacman -S gettext gcc autoconf libtool automake make doxygen c-ares libev
 
 # Instalação do libsodium
 export LIBSODIUM_VER=1.0.16

diff --git a/debian/control b/debian/control
@@ -8,15 +8,14 @@ Uploaders:
  Roger Shimizu <rosh@debian.org>
 Build-Depends:
  cmake (>= 3.20),
- asciidoc-base | asciidoc,
+ doxygen (>= 1.9.4),
  debhelper (>= 10),
  libc-ares-dev,
  libuv1-dev,
  libmbedtls-dev,
  libpcre2-dev,
  libsodium-dev (>= 1.0.12),
- pkg-config,
- xmlto
+ pkg-config
 Standards-Version: 4.1.1
 Rules-Requires-Root: no
 Homepage: https://www.shadowsocks.org