chore: update config for docs

[tonywu6]

Background

Documentation-related config requires updating.

Changed

• Added docs/CONTRIBUTING.md which includes instructions on locally building and previewing docs
• Updated docs/requirements.txt
  • Removed redundant dependencies
• Updated docs/conf.py
  • Removed redundant HTML-related config
• Fixed links that become invalid after config changes
• Fixed links that were no longer in the recommended format

NOT changed

Contents and translations

Source texts and translations may need to be updated. Check for warnings and/or missing translations locally after this PR.

Publishing in CI

Previously, doc publishing has been done using a GitHub Actions workflow that was privately maintained and opaque to repo developers. Starting on June 10, said workflow will cease to function.

Maintainers are encouraged to configure CI on a repo-by-repo basis. This PR does NOT update existing CI to enable publishing docs.

The general advice for publishing in CI is as follows:

1. Prerequisites are Python and Node. With GitHub Actions, that would be:

   - uses: actions/setup-node@v4
     with:
       node-version: "22"
   - uses: actions/setup-python@v5
     with:
       python-version: "3.10"

2. The building step should be the same as when working locally, that is:

   python -m pip install -r docs/requirements.txt
   secretflow-doctools build --lang en --lang zh_CN

3. The publish command is:

   secretflow-doctools publish \
     --name @secretflow/x-spec \
     --index-js docs/_build/esm/index.js

   The following options are required:

   • --name @secretflow/x-spec — name of the npm package
   • --index-js docs/_build/esm/index.js — path to the package entrypoint; this is the default location

   The following environment variables are also required:

   • DRY_RUN — publishing will proceed if and only if DRY_RUN=0; you may omit this during test runs

   • DOCTOOLS_PUBLISH_NPM_TOKEN — npm token, which should be configured as a secret; example using GitHub Actions:

   - run: |
       secretflow-doctools publish [...]
     env:
       DRY_RUN: "0" # omit in test runs
       DOCTOOLS_PUBLISH_NPM_TOKEN: ${{secrets.DOCTOOLS_PUBLISH_NPM_TOKEN}}

Important

Other things to note:

• The published version number is extracted from git tags. In CI, make sure that tags are fetched.
• The publish command will bail if it detects there are uncommitted changes at runtime (as a safety measure). In CI, make sure to either not generate additional files, or ignore them in gitignore.
• The publish command no longer sends out Webhook notifications. Configure a separate CI step after if needed.

[tongke6]

LGTM