@@ -8,4 +8,4 @@ releases or the commit log:
  - https://github.com/WoLpH/python-progressbar/releases
  - https://github.com/WoLpH/python-progressbar/commits/develop
 
-Hint: click on the `...` button to see the change message.
+Hint: the ``...`` button on a commit shows the full change message.
@@ -2,10 +2,8 @@
 Contributing
 ============
 
-Contributions are welcome, and they are greatly appreciated! Every
-little bit helps, and credit will always be given.
-
-You can contribute in many ways:
+Contributions are welcome: bug reports, fixes, features, and
+documentation.
 
 Types of Contributions
 ----------------------
@@ -36,25 +34,24 @@ is open to whoever wants to implement it.
 Write Documentation
 ~~~~~~~~~~~~~~~~~~~
 
-Python Progressbar could always use more documentation, whether as part of the
-official Python Progressbar docs, in docstrings, or even on the web in blog posts,
-articles, and such.
+The documentation lives in ``docs/`` and is built with Sphinx. The
+sections below cover the parts of that build that are easy to get wrong.
 
 Regenerating the API reference
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``docs/progressbar*.rst`` pages are generated once with ``sphinx-apidoc`` and then
 committed and hand-maintained, not regenerated on every build. Never pass ``-f``/``--force``
-when running it again — that silently discards hand-added options, such as
+when running it again: that silently discards hand-added options, such as
 ``docs/progressbar.bar.rst``'s ``:member-order: bysource``. If you add a new module under
 ``progressbar/``, generate its page the same way the rest were generated and link it into
 ``docs/progressbar.rst``'s ``Submodules`` toctree yourself::
 
     $ sphinx-apidoc -e -o docs/ progressbar */os_specific/* */six.py
 
 The docs build runs with ``-W`` (warnings fail the build), so a page that exists but isn't
-linked into a toctree fails immediately with "document isn't included in any toctree" —
-you'll know right away if you forgot this step.
+linked into a toctree fails immediately with "document isn't included in any toctree".
+You'll know right away if you forgot this step.
 
 Regenerating demo animations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -95,8 +92,6 @@ If you are proposing a feature:
 
 * Explain in detail how it would work.
 * Keep the scope as narrow as possible, to make it easier to implement.
-* Remember that this is a volunteer-driven project, and that contributions
-  are welcome :)
 
 Get Started!
 ------------
@@ -123,15 +118,14 @@ Ready to contribute? Here's how to set up `python-progressbar` for local develop
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
-
-    $ flake8 progressbar tests
-    $ py.test
-    $ tox
+5. When you're done making changes, check that your changes pass the
+   linter and the tests, including other Python versions with tox::
 
-   To get flake8 and tox, just pip install them into your virtualenv using the requirements file.
+    $ uv run ruff check progressbar tests
+    $ uv run pytest
+    $ uv run tox
 
-    $ pip install -r tests/requirements.txt
+   The ``uv sync`` from step 3 already installed all of these.
 
 6. Commit your changes and push your branch to GitHub with `git-flow-avh`_::
 
@@ -153,18 +147,17 @@ Pull Request Guidelines
 Before you submit a pull request, check that it meets these guidelines:
 
 1. The pull request should include tests.
-2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 2.7, 3.3, and for PyPy. Check
-   https://travis-ci.org/WoLpH/python-progressbar/pull_requests
-   and make sure that the tests pass for all supported Python versions.
+2. If the pull request adds functionality, the docs should be updated:
+   docstrings plus the relevant page under ``docs/``.
+3. The pull request should work for every supported Python version (see
+   ``requires-python`` in ``pyproject.toml``). CI runs the full matrix on
+   GitHub Actions for every pull request.
 
 Tips
 ----
 
 To run a subset of tests::
 
-	$ py.test tests/some_test.py
+    $ uv run pytest tests/some_test.py
 
 .. _git-flow-avh: https://github.com/petervanderdoes/gitflow
@@ -2,8 +2,8 @@
 progressbar2
 ##############################################################################
 
-A mature, typed terminal progress bar library for Python scripts that need
-custom widgets, clean output around prints and logs, multiple concurrent bars,
+A typed terminal progress bar library for Python. It handles custom
+widgets, clean output around prints and logs, multiple concurrent bars,
 unknown-length progress, and pipe-friendly CLI usage.
 
 .. image:: https://github.com/WoLpH/python-progressbar/actions/workflows/main.yml/badge.svg
@@ -36,7 +36,7 @@ Try it in your browser
 ==============================================================================
 
 Every example in the `documentation <https://progressbar-2.readthedocs.io/en/latest/>`_
-runs live in the page — press **Run** on any code block. No install required.
+runs live in the page. Press **Run** on any code block, no install required.
 
 Progress with clean logs
 ==============================================================================
@@ -151,17 +151,6 @@ CLI usage
 
     progressbar --progress --timer --eta --rate --bytes input.bin -o output.bin
 
-Feature highlights
-==============================================================================
-
-* Works as an iterable wrapper or a manually updated progress bar.
-* Supports custom widgets, colors, granular bars, animated markers, and labels.
-* Handles unknown-length iterators.
-* Supports multiple concurrent progress bars with ``MultiBar``.
-* Redirects stdout/stderr so regular output does not corrupt the active bar.
-* Includes a pipe-friendly ``progressbar`` command.
-* Ships typed package metadata.
-
 Known terminal caveats
 ==============================================================================
 
@@ -178,8 +167,8 @@ on the now defunct Google Code. Since that project was completely abandoned by
 its developer and the developer did not respond to email, I decided to fork the
 package.
 
-This package is still backwards compatible with the original progressbar package
-so you can safely use it as a drop-in replacement for existing projects.
+This package is still backwards compatible with the original progressbar
+package so you can use it as a drop-in replacement for existing projects.
 
 Links
 ==============================================================================
 
@@ -8,7 +8,7 @@ const RUN_TIMEOUT_MS = 30000;
 
 // Read the Docs serves the site under `/en/<version>/`, so root-absolute
 // asset paths 404 there. Derive the static root from this script's own
-// URL instead — it is the one path the browser always knows.
+// URL instead: it is the one path the browser always knows.
 const SCRIPT_ELEMENT =
   document.currentScript ||
   document.querySelector('script[src$="livecode/livecode.js"]');
@@ -127,9 +127,9 @@ function createPanel(container, source) {
     terminal,
     setStatus(stage) {
       const labels = {
-        loading: 'Downloading Python…',
-        installing: 'Installing progressbar2…',
-        ready: 'Running…',
+        loading: 'Downloading Python...',
+        installing: 'Installing progressbar2...',
+        ready: 'Running...',
         idle: '',
       };
       status.textContent = labels[stage] ?? '';
 
@@ -32,7 +32,7 @@ let pyodide = null;
 // reached some other way.
 const THREAD_ERROR_MARKER = "can't start new thread";
 const THREAD_ERROR_MESSAGE =
-  'This demo uses MultiBar’s `with` form, which starts a real OS ' +
+  'This demo uses MultiBar's `with` form, which starts a real OS ' +
   'thread. Browsers cannot provide that, so it cannot run here -- the ' +
   'animation above is the real output. See the source for the pattern.';
 
 
@@ -1,8 +1,16 @@
 # Vendored assets
 
-| File | Source | Version | Licence |
+| File | Source | Version | License |
 | --- | --- | --- | --- |
 | `xterm.js`, `xterm.css` | `@xterm/xterm` | 5.5.0 | MIT (`LICENSE-xterm.txt`) |
 
-Update by re-running the `npm pack` steps in Task 20 of
-`docs/superpowers/plans/2026-08-02-interactive-documentation.md`.
+Update (bump the version in both commands and this table):
+
+```bash
+npm pack @xterm/xterm@5.5.0
+tar -xzf xterm-xterm-5.5.0.tgz
+cp package/lib/xterm.js docs/_static/vendor/xterm.js
+cp package/css/xterm.css docs/_static/vendor/xterm.css
+cp package/LICENSE docs/_static/vendor/LICENSE-xterm.txt
+rm -rf package xterm-xterm-5.5.0.tgz
+```
@@ -49,6 +49,21 @@
     'demo',
 ]
 
+# `sphinx-autodoc-typehints` is a declared docs dependency but is
+# deliberately NOT enabled. It would move each annotation next to its
+# parameter description, which suits docstrings that never repeat a type
+# in prose -- but it cannot document this package. Enabling it fails the
+# `-W` build with 40 `error while formatting signature ... list assignment
+# index out of range` warnings, one per module-level callable *instance*
+# documented as a data member: every `CSINoArg`/`CSI` escape sequence
+# (`CLEAR_LINE`, `CUP`, `HIDE_CURSOR`, ...) and every `ColorGradient`
+# class attribute (`Bar.fg`, `JobStatusBar.success_fg_color`, ...). The
+# extension tries to resolve hints against the instance rather than its
+# `__call__`, and that pattern is pervasive here. Autodoc already renders
+# the annotations in the signature, so nothing is lost by leaving this
+# off. Do not re-enable without rebuilding from a clean `docs/_build`:
+# an incremental rebuild reuses cached doctrees and reports success.
+
 # Merge each class's `__init__` docstring into its class page. Constructor
 # arguments are user-facing -- `ProgressBar` alone takes more than fifteen
 # -- and without this the default ('class') renders only the class
 
@@ -4,5 +4,5 @@
 Examples
 ========
 
-The runnable examples now live in :doc:`widgets/index` and
+The runnable examples live in :doc:`widgets/index` and
 :doc:`howto/index`, each with an animation and an editable console.
@@ -6,14 +6,14 @@ progressbar2 began as a fork of the original ``progressbar`` package, once
 hosted on the now-defunct Google Code and abandoned by its author. The
 project has said ever since that it is "backwards compatible with the
 original progressbar package so you can safely use it as a drop-in
-replacement for existing projects" (see the project README). This page is
-about what that claim covers today, verified against the current source,
-and -- just as importantly -- what it does not cover.
+replacement for existing projects" (see the project README). This page
+covers what that claim means today, verified against the current source,
+and what it does not cover.
 
 What "drop-in" covers
 ==========================
 
-* **The import name.** ``import progressbar`` still works; only the PyPI
+* **The import name.** ``import progressbar`` still works. Only the PyPI
   distribution name changed, to ``progressbar2``, because the original
   ``progressbar`` name on PyPI belonged to the abandoned package.
 * **The core object lifecycle.** Construct a ``ProgressBar``, call
@@ -61,12 +61,9 @@ What it does not cover
 
 * **Python version support moves forward, not backward.** The currently
   supported floor is CPython 3.10 (see ``pyproject.toml``'s
-  ``requires-python``); this is a live constraint, not a compatibility
+  ``requires-python``). This is a live constraint, not a compatibility
   promise about older interpreters the original package may have targeted.
-  Consult the project's GitHub releases for the history of exactly when that
-  floor changed -- this repository's own ``CHANGES.rst`` points there rather
-  than keeping an inline log, so this page does not restate specific past
-  versions it cannot verify from the source tree.
+  The project's GitHub releases record when that floor changed.
 * **Most of today's public surface is new, with no equivalent in the
   original package**: ``MultiBar``, ``FastProgressBar``, the native
   ``speedups`` accelerator (see
@@ -85,6 +82,6 @@ What it does not cover
   removal eventually, and migrate off them when convenient rather than
   relying on them long-term.
 * **The format-string compatibility shim is narrow.** It only rewrites a
-  bare ``%s`` for ``Timer`` and ``ETA`` specifically; a custom widget outside
-  that inheritance chain that expects the same old-style placeholder is not
-  covered.
+  bare ``%s`` for ``Timer`` and ``ETA`` specifically. A custom widget
+  outside that inheritance chain that expects the same old-style
+  placeholder is not covered.
@@ -3,10 +3,9 @@ Performance and the fast path
 ===================================
 
 Wrapping a loop in a progress bar should not be the reason the loop gets
-slower. progressbar2 has three layers aimed at that, each optional and each
-falling back cleanly to the layer below it when unavailable. This page
-covers what each one does, when it applies, and the measured cost of each,
-so you know when reaching for one deliberately is worth it.
+slower. progressbar2 has three layers aimed at that: an always-on update
+gate, an automatic lean renderer, and an opt-in native iterator. This page
+covers what each one does, when it applies, and its measured cost.
 
 Layer 1: the integer gate (always on)
 ==========================================
@@ -32,25 +31,26 @@ formatting.
 
 The fast class is chosen automatically when *all* of the following hold:
 no explicit ``widgets=`` was given, ``fast`` was not passed as ``False``,
-no ``variables`` kwarg was given, ``unit`` is still the default ``'it'``,
+``variables`` is empty or not given, ``unit`` is still the default ``'it'``,
 ``unit_scale`` is off, ``postfix`` is unset, and the
 ``PROGRESSBAR_DISABLE_FASTPATH`` environment variable is not set. In other
 words: the common "just wrap my loop" case gets the lean renderer by
-default; anything that needs the widget system (a custom widget list, tqdm's
+default. Anything that needs the widget system (a custom widget list, tqdm's
 ``unit``/``postfix`` extras, dynamic ``Variable`` widgets) automatically
 gets the full ``ProgressBar`` instead. You can also construct
 :py:class:`~progressbar.fast.FastProgressBar` directly if you want the fast
 renderer without going through the shortcut -- see
 :doc:`../reference/progressbar`.
 
-Note that this dispatch only happens inside ``progressbar.progressbar()``.
+This dispatch only happens inside ``progressbar.progressbar()``.
 Constructing ``ProgressBar()`` yourself always gets the full class.
 
 Layer 3: the native iterator (opt-in via the ``fast`` extra)
 ==================================================================
 
-Separately, :py:meth:`ProgressBar.__iter__ <progressbar.bar.ProgressBar.__iter__>`
-checks whether the optional ``speedups`` package
+Separately, :py:meth:`ProgressBar.__iter__
+<progressbar.bar.ProgressBar.__iter__>` checks whether the optional
+``speedups`` package
 (``speedups.progressbar.FastBarIterator``) is importable. If it is, and
 ``PROGRESSBAR_DISABLE_FASTPATH`` is not set, iterating over *any* bar --
 fast or full -- dispatches to that native iterator instead of the
@@ -59,7 +59,7 @@ pure-Python generator. It counts items itself and calls back into the bar
 gate crossings, so the per-iteration counting that Layer 1 already made
 cheap in pure Python gets cheaper still.
 
-``speedups`` is not installed by default; install it with the ``fast``
+``speedups`` is not installed by default. Install it with the ``fast``
 extra:
 
 .. code:: sh
@@ -71,7 +71,7 @@ above Layer 1: it stops ``progressbar.progressbar()`` from choosing
 ``FastProgressBar``, stops ``__iter__`` from choosing the native iterator,
 *and* disables the integer gate itself in :py:meth:`ProgressBar.start()
 <progressbar.bar.ProgressBar.start>` -- with it set, every bar calls
-``update()`` on every single iteration, matching the pre-gate behaviour
+``update()`` on every single iteration, matching the pre-gate behavior
 exactly. That makes it a genuine "turn all of this off" switch, useful when
 debugging a rendering issue you want to rule the gate out of, not just an
 opt-out of the optional native accelerator.
@@ -81,8 +81,8 @@ Measured cost
 
 The following is reproduced from this repository's own benchmark suite
 (``benchmarks/report.md``, generated by ``python benchmarks/bench.py &&
-python benchmarks/report.py``; see that file for the full comparison against
-other libraries). Figures are from one measurement environment (CPython
+python benchmarks/report.py``, which also compares against other
+libraries). Figures are from one measurement environment (CPython
 3.13.12, macOS arm64, output to a real pty) and will vary by machine --
 re-run the benchmark rather than treating these as guarantees:
 
@@ -114,4 +114,4 @@ When to reach for which layer
   those features need the widget system that ``FastProgressBar`` skips.
 * Install the ``fast`` extra when the iteration count itself is large
   enough (hundreds of millions of items) that even Layer 1's per-iteration
-  cost is worth shaving further; for most scripts it isn't necessary.
+  cost is worth shaving further. For most scripts it isn't necessary.