Documentation publishing and maintenance¶

Public documentation¶

The official documentation site is innovationb1ue.github.io/hbase-driver. Markdown sources stay in docs/; MkDocs with the Material theme generates the website. The site includes task-based navigation, English/Chinese entry points, search, code-copy buttons, and light/dark appearance. The Chinese handbook is a detailed entry point, not a translation of every English page.

The site follows the repository's main branch. It is not yet a versioned archive of each PyPI release. Check the installed package version and limitations when using a new example with an older release.

What is configured¶

File	Purpose
`mkdocs.yml`	Site URL, theme, navigation, language/search options, strict link checks
`requirements-docs.txt`	Pinned top-level documentation build dependencies
`.github/workflows/docs.yml`	Build on documentation PRs; deploy main pushes and manual runs
`pyproject.toml`	PyPI Documentation link pointing to the site
`docs/complete_example.md`	Standalone copyable example, independent of legacy root-level scripts

The publishing setup changes documentation and configuration only. Python source and test-file changes are not prerequisites for building the website. Documentation tools are not runtime dependencies of hbase-driver; customers can still install the driver directly with pip, with venv optional.

Build and preview¶

From the checkout, install documentation tools into your chosen development environment:

python -m pip install -r requirements-docs.txt
python -m mkdocs build --strict
python -m mkdocs serve

A separate venv is optional but useful for isolating contributor tooling. Open the Local URL printed by MkDocs; the configured /hbase-driver/ base path is intentional. Build output goes into ignored site/; do not commit it.

The strict build fails on broken internal document links, missing navigation pages, and invalid heading links. External website availability and live HBase behavior are separate checks.

Automatic publication¶

Edit Markdown or the documentation configuration.
Run the strict build and review the rendered pages.
Commit only intended documentation/configuration files and push.
A pull request builds the site without deployment permission.
A matching push to main builds an artifact and deploys it through GitHub Pages.
Check the Documentation workflow, then verify the public homepage, Chinese handbook, search, and at least one deep link.

The workflow uses the github-pages environment and GitHub's short-lived identity token. No persistent deployment password is stored in the repository. Deployment permissions are limited to the main-branch deploy job. Only site/ is uploaded, never the source checkout, local environment files, or credentials.

Repository setting: Settings → Pages → Build and deployment → Source: GitHub Actions. This must remain enabled. After a failure, fix the documentation/configuration, push again, or manually run the Documentation workflow. Do not grant deployment rights to pull requests to bypass an error.

The separate existing integration CI can also run on a main push; its HBase tests are not executed by the documentation build.

Maintain examples honestly¶

Keep README focused on installation and navigation. Put detailed workflows in topical pages and link to them. Verify actual signatures, serialized requests, and return values rather than trusting method names alone.

Cookbook blocks marked  have independent data and assertions. Each requires an empty disposable table with cf; use the ownership pattern in the complete example. Validate against the project's HBase containers before claiming behavior works. Ordinary contextual snippets are not all standalone programs.

See verification scope for previously run checks. This documentation-only publication does not ship the local Python documentation-test harness or modifications to legacy Python scripts. Do not publish commands that depend on uncommitted code.

PyPI and documentation are separate releases¶

project.readme = "README.md" supplies the package description. The Documentation project URL supplies a link to this website. PyPI does not build the multi-page site. See the PyPA metadata guide.

Updating the website does not replace an existing PyPI description or its project-link metadata. Package version 1.1.1 carries the corrected README, Chinese guide entry, and official documentation URL; its Python source is unchanged from 1.1.0. Older PyPI releases retain their original descriptions and links.

Once a package points to this stable site URL, normal documentation corrections can deploy without another package release. Keep implementation changes, their tests, and release-specific compatibility information coordinated.