Add documentation

.gitignore

@@ -160,3 +160,8 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# macOS
+*.DS_Store
+.AppleDouble
+.LSOverride

.vscode/settings.json

@@ -16,10 +16,27 @@
     "MD036": false,
     "MD041": false
   },
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  },
+  "yaml.customTags": [
+    "!ENV scalar",
+    "!ENV sequence",
+    "!relative scalar",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+  ],
   "cSpell.words": [
     "funcs",
+    "initargs",
+    "inlinehilite",
+    "linenums",
     "pbar",
+    "pygments",
     "randint",
+    "starmap",
+    "superfences",
     "taskid"
   ]
 }

docs/features/break-exception.md

@@ -0,0 +1,75 @@
+# A `break` and an exception
+
+When the loop ends with a `break` or an exception, the progress bar stops with
+the last complete iteration.
+
+For example, the loop in the following code breaks during the 1235th iteration.
+
+```python
+for i in atpbar(range(2000)):
+    if i == 1234:
+        break
+    sleep(0.0001)
+```
+
+Since `i` starts with `0`, when `i` is `1234`, the loop is in its 1235th
+iteration. The last complete iteration is 1234. The progress bar stops at 1234.
+
+```plaintext
+  61.70% ::::::::::::::::::::::::                 |     1234 /     2000 |:  range(0, 2000)
+```
+
+As an example of an exception, in the following code, an exception is
+thrown during the 1235th iteration.
+
+```python
+for i in atpbar(range(2000)):
+    if i == 1234:
+        raise Exception
+    sleep(0.001)
+```
+
+The progress bar stops at the last complete iteration, 1234.
+
+```
+  61.70% ::::::::::::::::::::::::                 |     1234 /     2000 |:  range(0, 2000)
+Traceback (most recent call last):
+  File "<stdin>", line 3, in <module>
+Exception
+```
+
+This feature works as well with nested loops, threading, and multiprocessing.
+For example, in the following code, the loops in threads break at 1235th
+iteration.
+
+```python
+def func(n, name):
+    for i in atpbar(range(n), name=name):
+        if i == 1234:
+            break
+        sleep(0.001)
+
+
+n_workers = 5
+n_jobs = 10
+
+with flushing(), ThreadPoolExecutor(max_workers=n_workers) as executor:
+    for i in range(n_jobs):
+        n = randint(3000, 10000)
+        f = executor.submit(func, n, name=f'Job {i}')
+```
+
+All progress bars stop at 1234.
+
+```plaintext
+  23.97% :::::::::                                |     1234 /     5149 |:  Job 2
+  33.32% :::::::::::::                            |     1234 /     3703 |:  Job 4
+  35.09% ::::::::::::::                           |     1234 /     3517 |:  Job 0
+  13.47% :::::                                    |     1234 /     9162 |:  Job 3
+  27.35% ::::::::::                               |     1234 /     4512 |:  Job 1
+  32.07% ::::::::::::                             |     1234 /     3848 |:  Job 6
+  29.04% :::::::::::                              |     1234 /     4250 |:  Job 5
+  21.01% ::::::::                                 |     1234 /     5872 |:  Job 8
+  13.70% :::::                                    |     1234 /     9006 |:  Job 7
+  36.51% ::::::::::::::                           |     1234 /     3380 |:  Job 9
+```

docs/features/index.md

@@ -0,0 +1 @@
+# Features

docs/features/jupyter.md

@@ -0,0 +1,9 @@
+# On Jupyter Notebook
+
+On Jupyter Notebook, `atpbar` shows progress bars based on
+[widgets](https://ipywidgets.readthedocs.io).
+
+<img src="https://raw.githubusercontent.com/alphatwirl/notebook-atpbar-001/v1.0.1/images/20190304_01_atpbar_jupyter.gif" width="800">
+
+You can try interactively online:
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/alphatwirl/notebook-atpbar-001/master?filepath=atpbar.ipynb)

docs/features/non-tty.md

@@ -0,0 +1,14 @@
+# Non TTY device
+
+If neither on Jupyter Notebook or on a TTY device, `atpbar` is not able to show
+progress bars. `atpbar` occasionally prints the status.
+
+```
+03/04 09:17 :     1173 /     7685 ( 15.26%): Thread 0
+03/04 09:17 :     1173 /     6470 ( 18.13%): Thread 3
+03/04 09:17 :     1199 /     1199 (100.00%): Thread 4
+03/04 09:18 :     1756 /     2629 ( 66.79%): Thread 2
+03/04 09:18 :     1757 /     7685 ( 22.86%): Thread 0
+03/04 09:18 :     1757 /     6470 ( 27.16%): Thread 3
+03/04 09:19 :     2342 /     2629 ( 89.08%): Thread 2
+```

docs/guide/disable.md

@@ -0,0 +1,12 @@
+# How to disable progress bars
+
+The function `disable()` disables `atpbar`; progress bars will not be shown.
+
+```python
+from atpbar import disable
+
+disable()
+```
+
+This function needs to be called before `atpbar` or `find_reporter()` is used,
+typically at the beginning of the program.

docs/guide/index.md

@@ -0,0 +1 @@
+# User Guide

docs/guide/multiprocessing-pool.md

@@ -0,0 +1,35 @@
+# Multiprocessing.Pool
+
+An example with
+[`multiprocessing.Pool`](https://docs.python.org/3/library/multiprocessing.html#module-multiprocessing.pool):
+
+```python
+from multiprocessing import Pool, set_start_method
+from random import randint
+from time import sleep
+
+from atpbar import atpbar, find_reporter, flushing, register_reporter
+
+set_start_method('fork', force=True)
+
+
+def func(n, name):
+    for _ in atpbar(range(n), name=name):
+        sleep(0.001)
+
+
+n_processes = 4
+n_jobs = 10
+
+args = [(randint(1000, 10000), f'Job {i}') for i in range(n_jobs)]
+
+with (
+    flushing(),
+    Pool(
+        n_processes,
+        initializer=register_reporter,
+        initargs=(find_reporter(),),
+    ) as pool,
+):
+    pool.starmap(func, args)
+```

docs/guide/multiprocessing-process.md

@@ -0,0 +1,33 @@
+# Multiprocessing.Process
+
+An example with
+[`multiprocessing.Process`](https://docs.python.org/3/library/multiprocessing.html#the-process-class):
+
+```python
+from multiprocessing import Process, set_start_method
+from random import randint
+from time import sleep
+
+from atpbar import atpbar, find_reporter, flushing, register_reporter
+
+set_start_method('fork', force=True)
+
+
+def func(n, name, reporter):
+    register_reporter(reporter)
+    for _ in atpbar(range(n), name=name):
+        sleep(0.001)
+
+
+n_processes = 5
+
+with flushing():
+    processes = []
+    for i in range(n_processes):
+        n = randint(1000, 10000)
+        p = Process(target=func, args=(n, f'Job {i}', find_reporter()))
+        p.start()
+        processes.append(p)
+    for p in processes:
+        p.join()
+```

docs/guide/process-pool-executor.md

@@ -0,0 +1,35 @@
+# ProcessPoolExecutor
+
+An example with [`concurrent.futures.ProcessPoolExecutor`](https://docs.python.org/3/library/concurrent.futures.html#processpoolexecutor):
+
+```python
+import multiprocessing
+from concurrent.futures import ProcessPoolExecutor
+from random import randint
+from time import sleep
+
+from atpbar import atpbar, find_reporter, flushing, register_reporter
+
+multiprocessing.set_start_method('fork', force=True)
+
+
+def func(n, name):
+    for _ in atpbar(range(n), name=name):
+        sleep(0.001)
+
+
+n_workers = 5
+n_jobs = 10
+
+with (
+    flushing(),
+    ProcessPoolExecutor(
+        max_workers=n_workers,
+        initializer=register_reporter,
+        initargs=(find_reporter(),),
+    ) as executor,
+):
+    for i in range(n_jobs):
+        n = randint(1000, 10000)
+        f = executor.submit(func, n, name=f'Job {i}')
+```

docs/guide/thread-pool-executor.md

@@ -0,0 +1,27 @@
+# ThreadPoolExecutor
+
+An example with
+[`concurrent.futures.ThreadPoolExecutor`](https://docs.python.org/3/library/concurrent.futures.html#threadpoolexecutor):
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from random import randint
+from time import sleep
+
+from atpbar import atpbar, flushing
+
+
+def func(n, name):
+    for _ in atpbar(range(n), name=name):
+        sleep(0.001)
+
+
+n_workers = 5
+n_jobs = 10
+
+with flushing(), ThreadPoolExecutor(max_workers=n_workers) as executor:
+    for i in range(n_jobs):
+        n = randint(1000, 10000)
+        f = executor.submit(func, n, name=f'Job {i}')
+
+```

docs/guide/threading-thread.md

@@ -0,0 +1,30 @@
+# Threading
+
+An example with
+[`threading.Thread`](https://docs.python.org/3/library/threading.html#thread-objects):
+
+```python
+from random import randint
+from threading import Thread
+from time import sleep
+
+from atpbar import atpbar, flushing
+
+
+def func(n, name):
+    for _ in atpbar(range(n), name=name):
+        sleep(0.001)
+
+
+n_threads = 5
+
+with flushing():
+    threads = []
+    for i in range(n_threads):
+        n = randint(1000, 10000)
+        t = Thread(target=func, args=(n, f'Thread {i}'))
+        t.start()
+        threads.append(t)
+    for t in threads:
+        t.join()
+```

docs/index.md

@@ -0,0 +1,36 @@
+# atpbar
+
+_Progress bars_ for threading and multiprocessing tasks on the terminal and
+Jupyter Notebook.
+
+![Demo](demo.svg)
+
+## Introduction
+
+_atpbar_ can display multiple progress bars simultaneously growing to show the
+progress of each iteration of loops in
+[threading](https://docs.python.org/3/library/threading.html) or
+[multiprocessing](https://docs.python.org/3/library/multiprocessing.html)
+tasks. _atpbar_ can display progress bars on the terminal and [Jupyter
+Notebook](https://jupyter.org/).
+
+_atpbar_ started its development in 2015 and was the sub-package
+[_progressbar_](https://github.com/alphatwirl/alphatwirl/tree/v0.22.0/alphatwirl/progressbar)
+of alphatwirl. It became an independent package in 2019.
+
+You can try it on Jupyter Notebook online:
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/alphatwirl/notebook-atpbar-001/master?filepath=atpbar.ipynb)
+
+## Install
+
+You can install with `pip` from [PyPI](https://pypi.org/project/atpbar/):
+
+```bash
+pip install -U atpbar
+```
+
+To install with Jupyter Notebook support, use the following command:
+
+```bash
+pip install -U atpbar[jupyter]
+```

docs/overrides/main.html

@@ -0,0 +1 @@
+{% extends "base.html" %}