Skip to content

Commit aefce6f

Browse files
wolphwolph
committed
Expand reference, explanation and installation pages with visual guides
1 parent 54ad9bc commit aefce6f

5 files changed

Lines changed: 299 additions & 15 deletions

File tree

‎docs/_static/section-pages.css‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
.render-flow > ol,
2+
.install-options {
3+
display: grid;
4+
gap: 16px;
5+
margin: 24px 0;
6+
padding: 0;
7+
}
8+
.render-flow > ol {
9+
grid-template-columns: repeat(3, minmax(0, 1fr));
10+
list-style: none;
11+
counter-reset: render-step;
12+
}
13+
.render-flow > ol > li,
14+
[role="main"] .install-option.container {
15+
box-sizing: border-box;
16+
min-width: 0;
17+
padding: 20px;
18+
border: 1px solid var(--color-background-border);
19+
border-radius: 10px;
20+
background: var(--home-card-transfer);
21+
}
22+
.render-flow > ol > li {
23+
counter-increment: render-step;
24+
}
25+
.render-flow > ol > li::before {
26+
content: counter(render-step);
27+
display: block;
28+
margin-bottom: 12px;
29+
color: var(--home-accent);
30+
font-size: 1.6rem;
31+
font-weight: 750;
32+
}
33+
.render-flow > ol > li:nth-child(2),
34+
[role="main"] .install-option.container:nth-child(2) {
35+
background: var(--home-card-jobs);
36+
}
37+
.render-flow > ol > li:nth-child(3) {
38+
background: var(--home-card-logs);
39+
}
40+
.render-flow p,
41+
.install-option p {
42+
margin: 0 0 12px;
43+
}
44+
.render-flow p:last-child,
45+
.install-option > :last-child {
46+
margin-bottom: 0;
47+
}
48+
.install-options {
49+
grid-template-columns: repeat(2, minmax(0, 1fr));
50+
}
51+
.install-option .rubric {
52+
margin-top: 0;
53+
font-size: 1.1rem;
54+
}
55+
.install-option div[class*="highlight"] {
56+
margin: 16px 0 0;
57+
}
58+
.install-option pre {
59+
padding: 12px;
60+
font-size: 0.8rem;
61+
}
62+
@media (max-width: 640px) {
63+
.render-flow > ol,
64+
.install-options {
65+
grid-template-columns: 1fr;
66+
}
67+
}

‎docs/_templates/page.html‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,12 @@
55
{% if pagename == 'index' and builder == 'html' %}
66
<link rel="stylesheet" href="{{ pathto('_static/home.css', 1) }}">
77
{% endif %}
8-
{% if pagename in ('tutorial/index', 'howto/index') and builder == 'html' %}
8+
{% if pagename in ('tutorial/index', 'howto/index', 'reference/index', 'explanation/index', 'installation') and builder == 'html' %}
99
<link rel="stylesheet" href="{{ pathto('_static/guide-cards.css', 1) }}">
1010
{% endif %}
11+
{% if pagename in ('reference/index', 'explanation/index', 'installation') and builder == 'html' %}
12+
<link rel="stylesheet" href="{{ pathto('_static/section-pages.css', 1) }}">
13+
{% endif %}
1114
{% endblock %}
1215

1316
{% block body %}

‎docs/explanation/index.rst‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,70 @@
22
Explanation
33
===========
44

5-
Background on how the library works and why it is built this way.
5+
If a bar redraws less often than your loop runs, changes its output when
6+
piped to a file, or selects a different renderer, these guides explain why.
7+
8+
From an update to a line
9+
========================
10+
11+
A progress update usually follows these three steps. Forced updates can
12+
bypass the redraw checks, including the updates made when a bar starts
13+
and finishes.
14+
15+
.. container:: render-flow
16+
17+
1. **Record progress**
18+
19+
Keep the current value when your loop advances or you call
20+
``bar.update(value)``.
21+
22+
2. **Check whether a redraw is due**
23+
24+
An integer threshold skips most of the work in a fast loop.
25+
Calls that pass it are checked against timing and visible progress.
26+
27+
3. **Format and write the line**
28+
29+
When a redraw is due, build the display from widgets or the fast
30+
renderer's fixed format and write it to the output stream.
31+
32+
Understand the behaviour
33+
========================
34+
35+
.. container:: guide-card
36+
37+
.. rubric:: :doc:`Why doesn't every update redraw? <rendering-and-the-update-gate>`
38+
39+
Follow the integer threshold and timing checks that decide when a value
40+
change produces output. See how ``min_poll_interval``, ``poll_interval``
41+
and ``force=True`` affect the result.
42+
43+
.. container:: guide-card
44+
45+
.. rubric:: :doc:`Why does output change between terminals and logs? <terminal-detection>`
46+
47+
Trace terminal detection, colour support and width selection separately.
48+
Find which constructor arguments and environment variables control
49+
overwriting a line, using colour and sizing the bar.
50+
51+
.. container:: guide-card
52+
53+
.. rubric:: :doc:`What work does the fast path skip? <performance-and-the-fast-path>`
54+
55+
Separate the update gate, the automatically selected ``FastProgressBar``
56+
renderer and the optional native iterator. Learn when custom widgets
57+
need the full renderer and what the ``fast`` extra changes.
58+
59+
.. container:: guide-card
60+
61+
.. rubric:: :doc:`What carries over from the original progressbar? <backwards-compatibility>`
62+
63+
Check the shared import name and bar lifecycle, then find the modern
64+
names for deprecated arguments and attributes. See where compatibility
65+
ends, including Python version support and newer APIs.
666

767
.. toctree::
68+
:hidden:
869
:maxdepth: 1
970

1071
rendering-and-the-update-gate

‎docs/installation.rst‎

Lines changed: 79 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,98 @@
22
Installation
33
============
44

5-
The package is named ``progressbar2`` on PyPI (the module you import is
6-
``progressbar``) and requires Python 3.10 or later. Install it with pip:
5+
Install the ``progressbar2`` package, then import it as ``progressbar``.
6+
You need Python 3.10 or later.
7+
8+
1. Install the package
9+
======================
10+
11+
Choose the command that matches how you manage your Python environment:
12+
13+
.. container:: install-options
14+
15+
.. container:: install-option
16+
17+
.. rubric:: Install with pip
18+
19+
Use the Python environment where you will run your script:
20+
21+
.. code-block:: console
22+
23+
$ python -m pip install progressbar2
24+
25+
.. container:: install-option
26+
27+
.. rubric:: Add to a uv project
28+
29+
From an existing uv project, add the package as a dependency:
30+
31+
.. code-block:: console
32+
33+
$ uv add progressbar2
34+
35+
2. Check the import
36+
===================
37+
38+
Print the installed version from the same Python environment:
739

840
.. code-block:: console
941
10-
$ pip install progressbar2
42+
$ python -c "import progressbar; print(progressbar.__version__)"
1143
12-
Or with uv:
44+
In a uv project, run the check through uv:
1345

1446
.. code-block:: console
1547
16-
$ uv add progressbar2
48+
$ uv run python -c "import progressbar; print(progressbar.__version__)"
49+
50+
A version number confirms that Python can import the installed package.
51+
52+
3. Run your first bar
53+
=====================
54+
55+
Wrap a loop to track its progress:
1756

18-
The optional ``fast`` extra installs the native iterator accelerator used
19-
by the fast path (see :doc:`explanation/performance-and-the-fast-path`):
57+
.. demo:: tutorial/step1
58+
59+
The loop processes 100 steps. ``progressbar.progressbar()`` starts the bar,
60+
advances it as the loop runs and finishes it when the loop ends. The short
61+
sleep makes the movement visible. Replace it with your own work.
62+
63+
Optional native iterator
64+
========================
65+
66+
The standard installation includes the update gate and automatic fast
67+
renderer. The optional ``fast`` extra adds a native iterator for counting
68+
items in large loops:
2069

2170
.. code-block:: console
2271
23-
$ pip install 'progressbar2[fast]'
72+
$ python -m pip install 'progressbar2[fast]'
2473
25-
Confirm the install by printing the version:
74+
For a uv project:
2675

2776
.. code-block:: console
2877
29-
$ python -c "import progressbar; print(progressbar.__version__)"
78+
$ uv add 'progressbar2[fast]'
79+
80+
The examples work without this extra. The
81+
:doc:`fast-path explanation <explanation/performance-and-the-fast-path>`
82+
describes when the native iterator is used.
83+
84+
Keep building
85+
=============
86+
87+
.. container:: guide-card
88+
89+
.. rubric:: :doc:`Build a bar in five steps <tutorial/index>`
90+
91+
Start with the loop above, then control updates, set a total, choose
92+
widgets and print messages above the display.
93+
94+
.. container:: guide-card
95+
96+
.. rubric:: :doc:`Find a guide for your task <howto/index>`
3097

31-
If that prints a version number such as ``4.6.0``, continue with
32-
:doc:`tutorial/index`.
98+
Track file transfers, show several jobs together or add live values and
99+
colour to your progress display.

‎docs/reference/index.rst‎

Lines changed: 87 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,95 @@
22
Reference
33
=========
44

5-
Complete descriptions of the public API surface.
5+
Find constructor arguments, methods and command-line options for the part
6+
of progressbar2 you are using. Each reference explains the available controls
7+
and links to the corresponding classes and functions.
8+
9+
Bars and parallel work
10+
======================
11+
12+
.. container:: guide-card
13+
14+
.. rubric:: :doc:`Configure a ProgressBar <progressbar>`
15+
16+
Set the value range, widgets, output stream and redraw intervals.
17+
Look up ``ProgressBar`` methods and the related ``DataTransferBar``,
18+
``NullBar`` and ``FastProgressBar`` classes.
19+
20+
.. only:: html and not epub
21+
22+
.. container:: guide-preview
23+
24+
.. image:: /_static/demos/tutorial-step4.svg
25+
:target: progressbar.html
26+
:alt: A ProgressBar configured with a percentage, a bar and an ETA.
27+
28+
.. container:: guide-card
29+
30+
.. rubric:: :doc:`Manage rows with MultiBar <multibar>`
31+
32+
Control labels, row ordering and the display of waiting and finished
33+
jobs. ``MultiBar`` keeps the child bars together and redraws them from
34+
its background thread.
35+
36+
.. only:: html and not epub
37+
38+
.. container:: guide-preview
39+
40+
.. image:: /_static/demos/howto-multibar.svg
41+
:target: multibar.html
42+
:alt: MultiBar displaying several jobs as they advance and finish.
43+
44+
.. container:: guide-card
45+
46+
.. rubric:: :doc:`Choose a parallel execution API <parallel>`
47+
48+
Look up ``map``, ``imap``, ``amap`` and the other batch helpers.
49+
Compare worker pools, result ordering, concurrency limits and error
50+
handling, including reusable ``Pool`` and ``AsyncPool`` objects.
51+
52+
.. only:: html and not epub
53+
54+
.. container:: guide-preview
55+
56+
.. image:: /_static/demos/howto-parallel-execution.svg
57+
:target: parallel.html
58+
:alt: Parallel tasks with individual progress bars and an overall count.
59+
60+
Widgets, commands and modules
61+
=============================
62+
63+
.. container:: guide-card
64+
65+
.. rubric:: :doc:`Find the widget for your display <../widgets/index>`
66+
67+
Choose a percentage, timer, transfer speed or live value by what you need
68+
to show. The widget table identifies which displays need a known total,
69+
with a runnable example for each widget.
70+
71+
``Percentage``, ``Bar``, ``ETA``, ``Variable``
72+
73+
.. container:: guide-card
74+
75+
.. rubric:: :doc:`Look up command-line options <cli>`
76+
77+
Track bytes or lines moving through a pipe or between files with the
78+
``progressbar`` command. Check size, rate and output options, including
79+
the compatibility flags that are accepted but have no effect.
80+
81+
``progressbar`` and ``bar`` name the same command.
82+
83+
.. container:: guide-card
84+
85+
.. rubric:: :doc:`Browse the full module listing <../progressbar>`
86+
87+
Find classes, functions and modules in the generated API documentation,
88+
including helpers beyond the focused reference pages above.
89+
90+
``progressbar.bar``, ``progressbar.multi``, ``progressbar.widgets``
691

792
.. toctree::
93+
:hidden:
894
:maxdepth: 1
995

1096
progressbar

0 commit comments

Comments
 (0)