diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index b634a35f..ee7cae26 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -2,9 +2,9 @@ name: "CodeQL"
on:
push:
- branches: [ "develop" ]
+ branches: [ "master", "develop" ]
pull_request:
- branches: [ "develop" ]
+ branches: [ "master", "develop" ]
schedule:
- cron: "24 21 * * 1"
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index cb6eae7e..89bac84b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -2,7 +2,7 @@ name: docs console
on:
push:
- branches: [develop]
+ branches: [master, develop]
pull_request:
workflow_dispatch:
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index be123e86..a677a9f0 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -2,7 +2,7 @@ name: tox
on:
push:
- branches: [develop]
+ branches: [master, develop]
pull_request:
workflow_dispatch:
diff --git a/README.md b/README.md
index 9b411adc..65dc19cc 100644
--- a/README.md
+++ b/README.md
@@ -3,12 +3,12 @@
The fastest progress bar in Python, maintained since 2012.
-
-
+
+
-
+
Wrapping a fast loop in a progress bar can cost more than the loop
@@ -79,9 +79,9 @@ terminal through one `MultiBar`:
`gradient_colors` shifts a bar's fill color as its percentage grows, so
the download bar sweeps red through gold to green and the render bar
-sweeps sky blue into fuchsia. The scan bar has no percentage to sweep
-(its length is unknown), so `fixed_colors` gives its animated marker one
-unchanging cyan instead.
+sweeps sky blue into fuchsia. The scan spinner normally cycles through
+colours with its frames. Passing a single cyan colour keeps its colour
+unchanged while the marker spins.
"""
import sys
@@ -89,7 +89,7 @@ import time
import progressbar
from progressbar.terminal import ColorGradient, colors
-from progressbar.widgets import TFixedColors, TGradientColors
+from progressbar.widgets import TGradientColors
STEPS = 24
@@ -122,11 +122,8 @@ def main() -> None:
multibar['scan'] = progressbar.ProgressBar(
max_value=progressbar.UnknownLength,
widgets=[
- progressbar.Bar(
- marker=progressbar.AnimatedMarker(),
- fixed_colors=TFixedColors(
- fg_none=colors.cyan1, bg_none=None
- ),
+ progressbar.AnimatedMarker(
+ gradient_colors=TGradientColors(fg=colors.cyan1, bg=None),
),
],
)
diff --git a/docs/_ext/demo.py b/docs/_ext/demo.py
index 59e32fb0..8451d58d 100644
--- a/docs/_ext/demo.py
+++ b/docs/_ext/demo.py
@@ -7,6 +7,7 @@
from __future__ import annotations
+import hashlib
import html
import importlib.util
import pathlib
@@ -17,7 +18,7 @@
from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx.application import Sphinx
-from sphinx.errors import NoUri
+from sphinx.errors import ExtensionError, NoUri
from sphinx.util.osutil import relative_uri
if typing.TYPE_CHECKING:
@@ -116,6 +117,8 @@ def run(self) -> list[Node]:
here = ''
svg_uri = relative_uri(here, f'_static/demos/{demo.svg_path.name}')
source_uri = relative_uri(here, f'_static/examples/{stem}.py')
+ source_hash: str = hashlib.sha256(source.encode('utf-8')).hexdigest()
+ source_uri += f'?v={source_hash}'
container = nodes.container(classes=['demo'])
container += nodes.raw(
@@ -155,11 +158,29 @@ def copy_example_sources(app: Sphinx, exception: Exception | None) -> None:
)
+def validate_showcase_assets(_app: Sphinx) -> None:
+ """Check recordings embedded as raw HTML on the documentation homepage."""
+ name: str
+ for name in ('readme/colors', 'readme/multibar', 'readme/hero'):
+ svg_path: pathlib.Path = DEMOS_BY_NAME[name].svg_path
+ if not svg_path.is_file():
+ raise ExtensionError(
+ f'showcase animation not rendered: {name} '
+ f'(run: python scripts/render_demos.py --only {name})'
+ )
+
+
def setup(app: Sphinx) -> dict[str, typing.Any]:
app.add_directive('demo', DemoDirective)
+ app.connect('builder-inited', validate_showcase_assets)
app.connect('build-finished', copy_example_sources)
app.add_css_file('vendor/xterm.css')
app.add_css_file('livecode/livecode.css')
app.add_js_file('vendor/xterm.js')
- app.add_js_file('livecode/livecode.js')
+ app.add_js_file('vendor/addon-fit.js')
+ worker_path: pathlib.Path = REPO_ROOT / 'docs/_static/livecode/worker.js'
+ worker_hash: str = hashlib.sha256(worker_path.read_bytes()).hexdigest()
+ app.add_js_file(
+ 'livecode/livecode.js', **{'data-worker-version': worker_hash}
+ )
return {'parallel_read_safe': True, 'parallel_write_safe': True}
diff --git a/docs/_ext/page_assets.py b/docs/_ext/page_assets.py
new file mode 100644
index 00000000..971c7380
--- /dev/null
+++ b/docs/_ext/page_assets.py
@@ -0,0 +1,38 @@
+"""Register page assets with Sphinx so their URLs include content checksums."""
+
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+ from docutils import nodes
+ from sphinx.application import Sphinx
+
+
+def add_page_assets(
+ app: Sphinx,
+ pagename: str,
+ _templatename: str,
+ _context: dict[str, typing.Any],
+ _doctree: nodes.document | None,
+) -> None:
+ if app.builder is None or app.builder.name != 'html':
+ return
+ if pagename == 'index':
+ app.add_css_file('home.css', priority=900)
+ app.add_js_file('showcase.js', loading_method='defer', priority=900)
+ if pagename in (
+ 'tutorial/index',
+ 'howto/index',
+ 'reference/index',
+ 'explanation/index',
+ 'installation',
+ ):
+ app.add_css_file('guide-cards.css', priority=900)
+ if pagename in ('reference/index', 'explanation/index', 'installation'):
+ app.add_css_file('section-pages.css', priority=900)
+
+
+def setup(app: Sphinx) -> dict[str, bool]:
+ app.connect('html-page-context', add_page_assets)
+ return {'parallel_read_safe': True, 'parallel_write_safe': True}
diff --git a/docs/_static/brand.css b/docs/_static/brand.css
new file mode 100644
index 00000000..782e22ac
--- /dev/null
+++ b/docs/_static/brand.css
@@ -0,0 +1,41 @@
+/* Shared typography and controls for the homepage and Furo documentation. */
+body {
+ --home-accent: #6550b5;
+ --home-card-transfer: #e1f0ee;
+ --home-card-jobs: #eee5f7;
+ --home-card-logs: #f8edcf;
+ --home-surface: #efece5;
+}
+body[data-theme="dark"] {
+ --home-accent: #b9a5f0;
+ --home-card-transfer: #203a37;
+ --home-card-jobs: #352c44;
+ --home-card-logs: #403922;
+ --home-surface: #28272b;
+}
+@media (prefers-color-scheme: dark) {
+ body:not([data-theme="light"]) {
+ --home-accent: #b9a5f0;
+ --home-card-transfer: #203a37;
+ --home-card-jobs: #352c44;
+ --home-card-logs: #403922;
+ --home-surface: #28272b;
+ }
+}
+a { text-underline-offset: 0.18em; }
+a:focus-visible, button:focus-visible, input:focus-visible,
+textarea:focus-visible, [tabindex]:focus-visible {
+ outline: 3px solid #b87917;
+ outline-offset: 4px;
+}
+.sidebar-brand-text { font-weight: 750; letter-spacing: -0.035em; }
+.demo-button { background: #6550b5; color: #fff; }
+.visually-hidden {
+ position: absolute;
+ width: 1px;
+ height: 1px;
+ padding: 0;
+ overflow: hidden;
+ clip-path: inset(50%);
+ white-space: nowrap;
+}
diff --git a/docs/_static/demos/homepage-quickstart.svg b/docs/_static/demos/homepage-quickstart.svg
new file mode 100644
index 00000000..beac89c7
--- /dev/null
+++ b/docs/_static/demos/homepage-quickstart.svg
@@ -0,0 +1,60 @@
+
diff --git a/docs/_static/demos/howto-colors.svg b/docs/_static/demos/howto-colors.svg
index 585595fd..48c901d4 100644
--- a/docs/_static/demos/howto-colors.svg
+++ b/docs/_static/demos/howto-colors.svg
@@ -7,7 +7,7 @@
viewBox="0 0 1080 96"
>
Fixed and gradient bar colors
- Color a bar with a fixed color or a gradient that shifts with progress.
+ Choose a progress gradient and a solid colour for an animated spinner.
+
+
+
+
+ Three workers reporting task progress
+ Total 0 of 3 files | |sales.csv 0% | |users.csv 0% | |Total 0 of 3 files | |stock.csv 0% | |sales.csv 1% | |users.csv 1% | |Total 0 of 3 files | |stock.csv 1% | |sales.csv 1% | |users.csv 2% | |Total 0 of 3 files | |stock.csv 2% | |sales.csv 3% |# |users.csv 2% | |Total 0 of 3 files | |stock.csv 3% |# |sales.csv 3% |# |users.csv 3% |# |Total 0 of 3 files | |stock.csv 4% |# |sales.csv 3% |# |users.csv 4% |# |Total 0 of 3 files | |stock.csv 4% |# |sales.csv 5% |## |users.csv 5% |## |Total 0 of 3 files | |stock.csv 6% |## |sales.csv 5% |## |users.csv 5% |## |Total 0 of 3 files | |stock.csv 7% |## |sales.csv 6% |## |users.csv 6% |## |Total 0 of 3 files | |stock.csv 7% |## |sales.csv 7% |## |users.csv 7% |## |Total 0 of 3 files | |stock.csv 7% |## |sales.csv 8% |### |users.csv 8% |### |Total 0 of 3 files | |stock.csv 8% |### |sales.csv 9% |### |users.csv 9% |### |Total 0 of 3 files | |stock.csv 9% |### |sales.csv 9% |### |users.csv 10% |#### |Total 0 of 3 files | |stock.csv 10% |#### |sales.csv 10% |#### |users.csv 11% |#### |Total 0 of 3 files | |stock.csv 11% |#### |sales.csv 11% |#### |users.csv 11% |#### |Total 0 of 3 files | |stock.csv 12% |#### |sales.csv 11% |#### |users.csv 12% |#### |Total 0 of 3 files | |stock.csv 12% |#### |sales.csv 14% |##### |users.csv 13% |##### |Total 0 of 3 files | |stock.csv 13% |##### |sales.csv 14% |##### |users.csv 14% |##### |Total 0 of 3 files | |stock.csv 14% |##### |sales.csv 15% |###### |users.csv 15% |###### |Total 0 of 3 files | |stock.csv 15% |###### |sales.csv 16% |###### |users.csv 15% |###### |Total 0 of 3 files | |stock.csv 15% |###### |sales.csv 17% |###### |users.csv 16% |###### |Total 0 of 3 files | |stock.csv 16% |###### |sales.csv 18% |####### |users.csv 17% |###### |Total 0 of 3 files | |stock.csv 17% |###### |sales.csv 18% |####### |users.csv 18% |####### |Total 0 of 3 files | |stock.csv 18% |####### |sales.csv 19% |####### |users.csv 19% |####### |Total 0 of 3 files | |stock.csv 19% |####### |sales.csv 20% |######## |users.csv 19% |####### |Total 0 of 3 files | |stock.csv 19% |####### |sales.csv 21% |######## |users.csv 20% |######## |Total 0 of 3 files | |stock.csv 20% |######## |sales.csv 22% |######### |users.csv 21% |######## |Total 0 of 3 files | |stock.csv 21% |######## |sales.csv 22% |######### |users.csv 22% |######### |Total 0 of 3 files | |stock.csv 22% |######### |sales.csv 23% |######### |users.csv 23% |######### |Total 0 of 3 files | |stock.csv 22% |######### |sales.csv 24% |######### |users.csv 24% |######### |Total 0 of 3 files | |stock.csv 24% |######### |sales.csv 25% |########## |users.csv 24% |######### |Total 0 of 3 files | |stock.csv 24% |######### |sales.csv 26% |########## |users.csv 26% |########## |Total 0 of 3 files | |stock.csv 25% |########## |sales.csv 27% |########### |users.csv 26% |########## |Total 0 of 3 files | |stock.csv 26% |########## |sales.csv 28% |########### |users.csv 27% |########### |Total 0 of 3 files | |stock.csv 26% |########## |sales.csv 29% |########### |users.csv 28% |########### |Total 0 of 3 files | |stock.csv 28% |########### |sales.csv 29% |########### |users.csv 29% |########### |Total 0 of 3 files | |stock.csv 28% |########### |sales.csv 30% |############ |users.csv 30% |############ |Total 0 of 3 files | |stock.csv 29% |########### |sales.csv 30% |############ |users.csv 31% |############ |Total 0 of 3 files | |stock.csv 30% |############ |sales.csv 31% |############ |users.csv 32% |############# |Total 0 of 3 files | |stock.csv 30% |############ |sales.csv 33% |############# |users.csv 32% |############# |Total 0 of 3 files | |stock.csv 32% |############# |sales.csv 33% |############# |users.csv 33% |############# |Total 0 of 3 files | |stock.csv 32% |############# |sales.csv 34% |############# |users.csv 34% |############# |Total 0 of 3 files | |stock.csv 33% |############# |sales.csv 34% |############# |users.csv 35% |############## |Total 0 of 3 files | |stock.csv 34% |############# |sales.csv 36% |############## |users.csv 36% |############## |Total 0 of 3 files | |stock.csv 35% |############## |sales.csv 37% |############### |users.csv 36% |############## |Total 0 of 3 files | |stock.csv 35% |############## |sales.csv 38% |############### |users.csv 39% |############### |Total 0 of 3 files | |stock.csv 36% |############## |sales.csv 39% |############### |users.csv 39% |############### |Total 0 of 3 files | |stock.csv 37% |############### |sales.csv 39% |############### |users.csv 41% |################ |Total 0 of 3 files | |stock.csv 38% |############### |sales.csv 40% |################ |users.csv 42% |################# |Total 0 of 3 files | |stock.csv 39% |############### |sales.csv 40% |################ |users.csv 43% |################# |Total 0 of 3 files | |stock.csv 41% |################ |sales.csv 42% |################# |users.csv 43% |################# |Total 0 of 3 files | |stock.csv 41% |################ |sales.csv 44% |################## |users.csv 44% |################## |Total 0 of 3 files | |stock.csv 42% |################# |sales.csv 44% |################## |users.csv 45% |################## |Total 0 of 3 files | |stock.csv 43% |################# |sales.csv 45% |################## |users.csv 46% |################## |Total 0 of 3 files | |stock.csv 44% |################## |sales.csv 46% |################## |users.csv 46% |################## |Total 0 of 3 files | |stock.csv 44% |################## |sales.csv 47% |################### |users.csv 48% |################### |Total 0 of 3 files | |stock.csv 45% |################## |sales.csv 47% |################### |users.csv 49% |#################### |Total 0 of 3 files | |stock.csv 46% |################## |sales.csv 48% |################### |users.csv 49% |#################### |Total 0 of 3 files | |stock.csv 47% |################### |sales.csv 49% |#################### |users.csv 50% |#################### |Total 0 of 3 files | |stock.csv 47% |################### |sales.csv 50% |#################### |users.csv 51% |#################### |Total 0 of 3 files | |stock.csv 49% |#################### |sales.csv 50% |#################### |users.csv 52% |##################### |Total 0 of 3 files | |stock.csv 49% |#################### |sales.csv 51% |#################### |users.csv 54% |###################### |Total 0 of 3 files | |stock.csv 51% |#################### |sales.csv 53% |##################### |users.csv 54% |###################### |Total 0 of 3 files | |stock.csv 52% |##################### |sales.csv 53% |##################### |users.csv 56% |###################### |Total 0 of 3 files | |stock.csv 53% |##################### |sales.csv 54% |###################### |users.csv 56% |###################### |Total 0 of 3 files | |stock.csv 55% |###################### |sales.csv 56% |###################### |users.csv 57% |####################### |Total 0 of 3 files | |stock.csv 55% |###################### |sales.csv 57% |####################### |users.csv 58% |####################### |Total 0 of 3 files | |stock.csv 57% |####################### |sales.csv 57% |####################### |users.csv 59% |######################## |Total 0 of 3 files | |stock.csv 58% |####################### |sales.csv 58% |####################### |users.csv 60% |######################## |Total 0 of 3 files | |stock.csv 59% |######################## |sales.csv 59% |######################## |users.csv 60% |######################## |Total 0 of 3 files | |stock.csv 60% |######################## |sales.csv 60% |######################## |users.csv 61% |######################### |Total 0 of 3 files | |stock.csv 61% |######################### |sales.csv 61% |######################### |users.csv 61% |######################### |Total 0 of 3 files | |stock.csv 61% |######################### |sales.csv 61% |######################### |users.csv 63% |######################### |Total 0 of 3 files | |stock.csv 63% |######################### |sales.csv 63% |######################### |users.csv 63% |######################### |Total 0 of 3 files | |stock.csv 63% |######################### |sales.csv 64% |########################## |users.csv 64% |########################## |Total 0 of 3 files | |stock.csv 64% |########################## |sales.csv 64% |########################## |users.csv 66% |########################### |Total 0 of 3 files | |stock.csv 65% |########################## |sales.csv 65% |########################## |users.csv 66% |########################### |Total 0 of 3 files | |stock.csv 65% |########################## |sales.csv 66% |########################### |users.csv 67% |########################### |Total 0 of 3 files | |stock.csv 67% |########################### |sales.csv 67% |########################### |users.csv 67% |########################### |Total 0 of 3 files | |stock.csv 67% |########################### |sales.csv 67% |########################### |users.csv 70% |############################ |Total 0 of 3 files | |stock.csv 68% |########################### |sales.csv 68% |########################### |users.csv 71% |############################# |Total 0 of 3 files | |stock.csv 69% |############################ |sales.csv 69% |############################ |users.csv 71% |############################# |Total 0 of 3 files | |stock.csv 69% |############################ |sales.csv 70% |############################ |users.csv 72% |############################# |Total 0 of 3 files | |stock.csv 70% |############################ |sales.csv 71% |############################# |users.csv 73% |############################# |Total 0 of 3 files | |stock.csv 71% |############################# |sales.csv 71% |############################# |users.csv 74% |############################## |Total 0 of 3 files | |stock.csv 72% |############################# |sales.csv 72% |############################# |users.csv 75% |############################## |Total 0 of 3 files | |stock.csv 73% |############################# |sales.csv 73% |############################# |users.csv 75% |############################## |Total 0 of 3 files | |stock.csv 73% |############################# |sales.csv 74% |############################## |users.csv 76% |############################### |Total 0 of 3 files | |stock.csv 74% |############################## |sales.csv 76% |############################### |users.csv 77% |############################### |Total 0 of 3 files | |stock.csv 75% |############################## |sales.csv 76% |############################### |users.csv 79% |################################ |Total 0 of 3 files | |stock.csv 76% |############################### |sales.csv 77% |############################### |users.csv 80% |################################ |Total 0 of 3 files | |stock.csv 77% |############################### |sales.csv 78% |############################### |users.csv 80% |################################ |Total 0 of 3 files | |stock.csv 78% |############################### |sales.csv 79% |################################ |users.csv 81% |################################# |Total 0 of 3 files | |stock.csv 79% |################################ |sales.csv 79% |################################ |users.csv 83% |################################## |Total 0 of 3 files | |stock.csv 80% |################################ |sales.csv 80% |################################ |users.csv 83% |################################## |Total 0 of 3 files | |stock.csv 81% |################################# |sales.csv 81% |################################# |users.csv 84% |################################## |Total 0 of 3 files | |stock.csv 81% |################################# |sales.csv 82% |################################# |users.csv 85% |################################## |Total 0 of 3 files | |stock.csv 82% |################################# |sales.csv 83% |################################## |users.csv 87% |################################### |Total 0 of 3 files | |stock.csv 83% |################################## |sales.csv 84% |################################## |users.csv 87% |################################### |Total 0 of 3 files | |stock.csv 84% |################################## |sales.csv 84% |################################## |users.csv 89% |#################################### |Total 0 of 3 files | |stock.csv 85% |################################## |sales.csv 86% |################################### |users.csv 89% |#################################### |Total 0 of 3 files | |stock.csv 86% |################################### |sales.csv 86% |################################### |users.csv 90% |#################################### |Total 0 of 3 files | |stock.csv 87% |################################### |sales.csv 87% |################################### |users.csv 91% |##################################### |Total 0 of 3 files | |stock.csv 87% |################################### |sales.csv 88% |#################################### |users.csv 92% |##################################### |Total 0 of 3 files | |stock.csv 88% |#################################### |sales.csv 89% |#################################### |users.csv 92% |##################################### |Total 0 of 3 files | |stock.csv 89% |#################################### |sales.csv 89% |#################################### |users.csv 94% |###################################### |Total 0 of 3 files | |stock.csv 90% |#################################### |sales.csv 90% |#################################### |users.csv 94% |###################################### |Total 0 of 3 files | |stock.csv 91% |##################################### |sales.csv 91% |##################################### |users.csv 95% |###################################### |Total 0 of 3 files | |stock.csv 91% |##################################### |sales.csv 92% |##################################### |users.csv 96% |####################################### |Total 0 of 3 files | |stock.csv 92% |##################################### |sales.csv 93% |###################################### |users.csv 96% |####################################### |Total 0 of 3 files | |stock.csv 93% |###################################### |sales.csv 94% |###################################### |users.csv 97% |####################################### |Total 0 of 3 files | |stock.csv 94% |###################################### |sales.csv 94% |###################################### |users.csv 98% |######################################## |Total 0 of 3 files | |stock.csv 95% |###################################### |sales.csv 95% |###################################### |users.csv 99% |######################################## |Total 0 of 3 files | |stock.csv 95% |###################################### |sales.csv 95% |###################################### |sales.csv 96% |####################################### |Total 1 of 3 files |########### |stock.csv 96% |####################################### |sales.csv 96% |####################################### |Total 1 of 3 files |########### |stock.csv 97% |####################################### |sales.csv 98% |######################################## |Total 1 of 3 files |########### |stock.csv 98% |######################################## |sales.csv 99% |######################################## |Total 1 of 3 files |########### |sales.csv 99% |######################################## |Total 2 of 3 files |###################### |Total 3 of 3 files |#################################|
+
diff --git a/docs/_static/demos/howto-prefix-suffix.svg b/docs/_static/demos/howto-prefix-suffix.svg
index 983e7ea7..ddade224 100644
--- a/docs/_static/demos/howto-prefix-suffix.svg
+++ b/docs/_static/demos/howto-prefix-suffix.svg
@@ -1,13 +1,13 @@