Python-Guide-CN: a Sphinx build of a translated Python guide with a stale topic list
Python best-practices guide. The Chinese translation of 'The Hitchhiker's Guide to Python'.
At a glance
- What is it?
- Prodesire/Python-Guide-CN is the Chinese translation of the Hitchhiker's Guide to Python, packaged as a Sphinx site built by uv and make. The prose is a translation project, but what you actually install is a small documentation toolchain with an out-of-date topic list and a pinned upstream commit.
- Who is it for?
- Adopt this repository if you are a Chinese-speaking developer who wants the Hitchhiker's Guide to Python as a local, offline Sphinx site and who is willing to read it beside the current English text. Do not adopt it as a source of current packaging, testing or server advice: the topic list still names Py2exe, bbfreeze, Fabric and Jenkins, which is a snapshot of an older toolchain rather than a view of what the guide says now.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- Mainly Batchfile, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Prodesire/Python-Guide-CN4,467 ★ · +28
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| Prodesire/Python-Guide-CN | 4.4k | 4.5k |
28 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
diff.txt holds the one commit that decides how current the text is
A translation fork of a living document needs one thing the original does not: a record of how far it has been carried. Python-Guide-CN keeps that record in a file named diff.txt at the repository root, and the translation instructions turn it into a procedure. The contributor updates the python-guide repository and the master branch of this one, opens diff.txt to find the commit number the current translation corresponds to on the original side, diffs that commit against the newest master in python-guide, translates the delta, and writes the new upstream commit number back into diff.txt before opening a merge request.
That single file is the honest freshness signal for the whole project. No version marker is published, so diff.txt is where a reader should look first. If it points at a commit from years ago, the Chinese pages are a faithful snapshot rather than a mirror of the English guide, and no amount of README wording changes that. It is an unglamorous mechanism and a better one than a README claiming the guide is continuously updated while nothing records the gap.
make install refuses to run without uv on PATH
The build path is three make targets, and the README is explicit about the order. Download the zip or clone the repository, enter the root directory, then:
make help
make install
make htmlmake help prints the four targets it advertises, which are install, html, serve and clean. make install is where the toolchain is pinned. The rule depends on pyproject.toml, uv.lock and the Makefile itself, and before doing anything it checks that uv is on PATH, printing a message pointing at the uv documentation and exiting non-zero if the command is missing. It then runs uv sync against the lockfile, with the Python version defaulted to 3.12 in the Makefile and overridable through PYTHON_VERSION.
What uv sync installs is small and specific: sphinx>=7.4,<8, sphinx-sitemap>=2.9,<3 and sphinxcontrib-websupport>=2,<3. The upper bounds mean an upgrade is a deliberate edit to pyproject.toml followed by a lock refresh, not something that happens on its own. The project is declared as package = false under tool.uv, so nothing from this repository is installed as a library. You are installing a documentation toolchain, not Python-Guide-CN itself.
make serve moves the port to 8005 and leaves the rest to Sphinx
After the install, one target produces files and one produces a site. make html delegates to the docs directory and touches a .nojekyll marker inside docs/_build/html, so the output works on a static host that would otherwise ignore underscored directories. make serve depends on the same html target, then changes into the build directory and serves it with the standard library:
cd $(BUILD_DIR)/html && $(VENV_PYTHON) -m http.server $(PORT)The port is 8005, not the usual default, and the Makefile exposes PORT as an override for readers who need another. Because the server is Python's own module rather than a documentation preview server, what you see is the built HTML and nothing more: no rebuild on file change, no search index refresh, no live reload. Editing a page under docs/ means rerunning make html.
One detail worth knowing: install is a dependency of html, so editing pyproject.toml or uv.lock invalidates the .venv/.installed stamp and the next build re-runs uv sync. Nothing invalidates the stamp when a source page changes, which is why a rebuild is manual.
The topic list still points at Py2exe, bbfreeze and Jenkins
The README enumerates what the guide covers, and the enumeration does not match a project that requires Python 3.12 or newer. Listed topics include Py2app, Py2exe and bbfreeze. The list also names Fabric for remote execution and Jenkins and tox for testing, both of which have been largely displaced in current workflows. The same list covers Pip, Virtualenv, NumPy and matplotlib, entries that survive.
The mismatch is not a defect in the build; it is inherited content. A translation of an English guide inherits the English guide's table of contents. Tracking translation state in one commit number rather than by topic is why the drift goes unnoticed: the build infrastructure moved to uv and locked Sphinx 7.4, while the list of subjects stayed where the original left it. The last push was on 2026-10-27, so that split is live today rather than a historical artefact. Anyone choosing this repository for its advice on packaging should expect to read about PyInstaller-era workflows and should read the current English guide alongside it.
Two Makefiles, make.bat on Windows, and every Sphinx builder forwarded from the root
The repository holds a root Makefile, a docs directory with its own Makefile, and make.bat with makehtml.bat for Windows contributors who cannot run the root targets. The root Makefile does not build anything itself. It resolves the virtualenv paths, then hands control down:
$(MAKE) -C docs html SPHINXBUILD=$(SPHINXBUILD)Nearly every Sphinx builder is exposed as a root target, listed in DOC_TARGETS: dirhtml, singlehtml, epub, latexpdf, man, gettext, linkcheck, doctest, xml, netlify and others. Each depends on install, so any of them triggers uv sync when the lockfile has changed. That is a wider surface than most readers will use, and it is worth knowing that make latexpdf or make linkcheck are available without descending into docs/ by hand.
The two-layer arrangement has a cost. Because the root forwards rather than wraps, a failure inside docs/ surfaces with make's nested invocation in the output. A .travis.yml at the root is a second signal of age: continuous integration configured for a repository whose actual build now depends on uv and a lockfile.
make clean empties docs/_build but leaves the virtualenv alone
Cleaning is one line. make clean runs rm -rf against the contents of docs/_build, which removes the generated HTML and the .nojekyll marker without touching the .venv directory or the install stamp.
That split has a practical consequence for CI. After a clean checkout the next make html still pays for the full uv sync, but on a reused runner where only the docs changed, the stamp survives and the build goes straight to Sphinx. If pyproject.toml or uv.lock were touched, the stamp is invalidated and uv sync runs again against the lockfile, which is the point of pinning.
Where a translated fork differs from reading the English guide
The alternative to this repository is the original Hitchhiker's Guide to Python at realpython/python-guide, which the README names as the source. The difference in approach is the whole point. The English guide is maintained in one place by one process; this fork inserts a second process, translation, between the upstream commit and the reader. That process costs latency, since a change upstream is invisible until a contributor translates it and updates diff.txt, and it produces a coverage gap rather than a mismatch, because what is missing is newer text, not wrong text.
What the fork adds is a local, offline copy in Chinese and a buildable Sphinx site. That matters for readers behind a slow link or on a network where the English site is awkward to reach, and for teams that want the guide versioned alongside their own documentation tooling. What it does not add is freshness, and the mechanism in diff.txt is how you check that for yourself rather than trusting the README's claim that the guide is continuously updated. One legal detail travels with the text: a LICENSE file sits at the repository root, but the licence identifier the repository API reports is NOASSERTION, and the README credits the original without naming a licence, so anyone republishing the Chinese pages should read that file first.
Editorial conclusion
Adopt this repository if you are a Chinese-speaking developer who wants the Hitchhiker's Guide to Python as a local, offline Sphinx site and who is willing to read it beside the current English text. Do not adopt it as a source of current packaging, testing or server advice: the topic list still names Py2exe, bbfreeze, Fabric and Jenkins, which is a snapshot of an older toolchain rather than a view of what the guide says now. The build side is not the problem, since uv, uv.lock and a pinned Sphinx 7.4 range keep make html and make serve reproducible on Python 3.12. Verify one thing before anything else: open diff.txt and read the upstream commit number it holds, because that single line is the only measure of how far the translation has been carried, and no README wording can substitute for it.
Frequently asked questions
How do I build the Python-Guide-CN documentation site locally?
Run make install to create a virtualenv with uv from pyproject.toml and uv.lock, then run make html to build into docs/_build/html. make serve builds and serves the same output at http://localhost:8005/.
What does diff.txt track in Python-Guide-CN?
It records the commit number on the original python-guide project that the current translation corresponds to. The translation procedure diffs that commit against the newest master upstream, translates the changes, then writes the new commit number back into diff.txt.
Does Python-Guide-CN need uv and Python 3.12 to build?
Yes. make install checks that uv is on PATH and exits with a pointer to the uv documentation if it is missing, and pyproject.toml sets requires-python to >=3.12 while the Makefile defaults PYTHON_VERSION to 3.12.
Which Python packages does the Python-Guide-CN build install?
Three: sphinx>=7.4,<8, sphinx-sitemap>=2.9,<3 and sphinxcontrib-websupport>=2,<3. The version ranges have upper limits, so upgrading means editing pyproject.toml and refreshing uv.lock.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/prodesire-python-guide-cn)Star history chart for your README
[](https://hysenlabs.com/projects/prodesire-python-guide-cn)Was this useful?