docs: api

src/ocrmypdf/api.py

@@ -55,12 +55,15 @@ def configure_logging(
     """Set up logging.
 
     Before calling :func:`ocrmypdf.ocr()`, you can use this function to
-    configure logging, if you want ocrmypdf's output to look like the ocrmypdf
+    configure logging if you want ocrmypdf's output to look like the ocrmypdf
     command line interface. It will register log handlers, log filters, and
     formatters, configure color logging to standard error, and adjust the log
     levels of third party libraries. Details of this are fine-tuned and subject
     to change. The ``verbosity`` argument is equivalent to the argument
-    ``--verbose`` and applies those settings.
+    ``--verbose`` and applies those settings. If you have a wrapper
+    script for ocrmypdf and you want it to be very similar to ocrmypdf, use this
+    function; if you are using ocrmypdf as part of an application that manages
+    its own logging, you probably do not want this function.
 
     If this function is not called, ocrmypdf will not configure logging, and it
     is up to the caller of ``ocrmypdf.ocr()`` to set up logging as it wishes using
@@ -79,12 +82,10 @@ def configure_logging(
 
     Args:
         verbosity: Verbosity level.
-        progress_bar_friendly: Install the TqdmConsole log handler, which is
-            compatible with the tqdm progress bar; without this log messages will
-            overwrite the progress bar.
-        manage_root_logger: Configure the process's root logger, to ensure
-            all log output is sent through
-        plugin_manager: The plugin manager.
+        progress_bar_friendly: If True (the default), install a custom log handler
+            that is compatible with progress bars and colored output.
+        manage_root_logger: Configure the process's root logger.
+        plugin_manager: The plugin manager, used for obtaining the custom log handler.
 
     Returns:
         The toplevel logger for ocrmypdf (or the root logger, if we are managing it).

src/ocrmypdf/pluginspec.py

@@ -30,7 +30,14 @@ hookspec = pluggy.HookspecMarker('ocrmypdf')
 
 @hookspec(firstresult=True)
 def get_logging_console() -> Handler:
-    """Returns a logging handler. Should be configured to handle progress bars."""
+    """Returns a custom logging handler.
+
+    Generally this is necessary when both logging output and a progress bar are both
+    outputting to ``sys.stderr``.
+
+    Note:
+        This is a :ref:`firstresult hook<firstresult>`.
+    """
 
 
 @hookspec
@@ -78,11 +85,16 @@ def get_executor(progressbar_class) -> Executor:
     distributed environment.
 
     OCRmyPDF's executors are analogous to the standard Python executors in
-    ``conconcurrent.futures``, but they do not work the same way.
+    ``conconcurrent.futures``, but they do not work the same way. Executors may
+    be reused for different, unrelated batch operations, since all of the context
+    for a given job are passed to :meth:`Executor.__call__`.
 
     Should be of type :class:`Executor` or otherwise conforming to the protocol
     of that call.
 
+    Arguments:
+        progressbar_class: A progress bar class, which will be created when
+
     Note:
         This hook will be called from the main process, and may modify global state
         before child worker processes are forked.
@@ -93,11 +105,15 @@ def get_executor(progressbar_class) -> Executor:
 
 @hookspec(firstresult=True)
 def get_progressbar_class():
-    """Called to obtain a class that can be used to create progress bars.
+    """Called to obtain a class that can be used to monitor progress.
+
+    A progress bar is assumed, but this could be used for any type of monitoring.
 
     The class should follow a tqdm-like protocol. Calling the class should return
     a new progress bar object, which is activated with ``__enter__`` and terminated
     ``__exit__``. An update method is called whenever the progress bar is updated.
+    Progress bar objects will not be reused; a new one will be created for each
+    group of tasks.
 
     The progress bar is held in the main process/thread and not updated by child
     process/threads. When a child notifies the parent of completed work, the
@@ -105,6 +121,12 @@ def get_progressbar_class():
 
     The arguments are the same as `tqdm <https://github.com/tqdm/tqdm>`_ accepts.
 
+    Progress bars should never write to ``sys.stdout``, or they will corrupt the
+    output if OCRmyPDF writes a PDF to standard output.
+
+    The type of events that OCRmyPDF reports to a progress bar may change in
+    minor releases.
+
     Here is how OCRmyPDF will use the progress bar:
 
     Example: