Merge pull request #1375 from keewis/format-docs

string formatting guide

5 files changed, 128 insertions, 1 deletions

diff --git a/CHANGES b/CHANGES
index e53cc5b..a46866a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -17,6 +17,7 @@ Pint Changelog
 - Fix default format for Measurement class (Issue #1300)
 - Fix parsing of pretty units with same exponents but different sign. (Issue #1360)
 - Convert the application registry to a wrapper object (Issue #1365)
+- Add documentation for the string format options (Issue #1357, #1375)
 
 ### Breaking Changes
 
diff --git a/docs/conf.py b/docs/conf.py
index 67e156c..2441af9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -42,6 +42,8 @@ extensions = [
     "sphinx.ext.mathjax",
     "matplotlib.sphinxext.plot_directive",
     "nbsphinx",
+    "IPython.sphinxext.ipython_directive",
+    "IPython.sphinxext.ipython_console_highlighting",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -109,6 +111,10 @@ pygments_style = "sphinx"
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
+# -- Options for extensions ----------------------------------------------------
+# napoleon
+napoleon_preprocess_types = True
+
 
 # -- Options for HTML output ---------------------------------------------------
 
@@ -321,7 +327,13 @@ epub_copyright = copyright
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "dask": ("https://docs.dask.org/en/latest", None),
+    "sparse": ("https://sparse.pydata.org/en/latest/", None),
+}
 
 # -- Doctest configuration -----------------------------------------------------
 
diff --git a/docs/formatting.rst b/docs/formatting.rst
new file mode 100644
index 0000000..74fb8bd
--- /dev/null
+++ b/docs/formatting.rst
@@ -0,0 +1,111 @@
+.. _formatting:
+.. currentmodule:: pint
+
+
+.. ipython:: python
+   :suppress:
+
+   import pint
+
+
+String formatting
+=================
+The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings (e.g.
+through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format
+specifications <formatspec>`. The basic format is:
+
+.. code-block:: none
+
+   [magnitude format][modifier][unit format]
+
+where each part is optional and the order of these is arbitrary.
+
+In case any part (except the modifier) is omitted, the corresponding value in
+:py:attr:`Quantity.default_format` or :py:attr:`Unit.default_format` is filled in. If
+that is not set (it evaluates to ``False``), :py:attr:`UnitRegistry.default_format` is
+used.  If both are not set, the global default of ``"D"`` and the magnitude's default
+format are used instead.
+
+.. note::
+
+   Modifiers may be used without specifying any format: ``"~"`` is a valid format
+   specification.
+
+
+Unit Format Specifications
+--------------------------
+The :py:class:`Unit` class ignores the magnitude format part, and the unit format
+consists of just the format type.
+
+Let's look at some examples:
+
+.. ipython:: python
+
+   ureg = pint.UnitRegistry()
+   u = ureg.kg * ureg.m / ureg.s ** 2
+
+   f"{u:P}"  # using the pretty format
+   f"{u:~P}"  # short pretty
+   f"{u:P~}"  # also short pretty
+
+   # default format
+   u.default_format
+   ureg.default_format
+   str(u)  # default: default
+   f"{u:~}"  # default: short default
+   ureg.default_format = "C"  # registry default to compact
+   str(u)  # default: compact
+   f"{u}"  # default: compact
+   u.default_format = "P"
+   f"{u}"  # default: pretty
+   u.default_format = ""  # TODO: switch to None
+   ureg.default_format = ""  # TODO: switch to None
+   f"{u}"  # default: default
+
+Unit Format Types
+-----------------
+``pint`` comes with a variety of unit formats:
+
+======= =============== ======================================================================
+Spec    Name            Example
+======= =============== ======================================================================
+``D``   default         ``kilogram * meter / second ** 2``
+``P``   pretty          ``kilogram·meter/second²``
+``H``   HTML            ``kilogram meter/second<sup>2</sup>``
+``L``   latex           ``\frac{\mathrm{kilogram} \cdot \mathrm{meter}}{\mathrm{second}^{2}}``
+``Lx``  latex siunitx   ``\si[]{\kilo\gram\meter\per\second\squared}``
+``C``   compact         ``kilogram*meter/second**2``
+======= =============== ======================================================================
+
+Quantity Format Specifications
+------------------------------
+The magnitude format is forwarded to the magnitude (for a unit-spec of ``H`` the
+magnitude's ``_repr_html_`` is called).
+
+Let's look at some more examples:
+
+.. ipython:: python
+
+    q = 1e-6 * u
+
+    # modifiers
+    f"{q:~P}"  # short pretty
+    f"{q:~#P}"  # compact short pretty
+    f"{q:P#~}"  # also compact short pretty
+
+    # additional magnitude format
+    f"{q:.2f~#P}"  # short compact pretty with 2 float digits
+    f"{q:#~}"  # short compact default
+
+Quantity Format Types
+---------------------
+There are no special quantity formats yet.
+
+Modifiers
+---------
+======== =================================================== ================================
+Modifier Meaning                                             Example
+======== =================================================== ================================
+``~``    Use the unit's symbol instead of its canonical name ``kg·m/s²`` (``f"{u:~P}"``)
+``#``    Call :py:meth:`Quantity.to_compact` first           ``1.0 m·mg/s²`` (``f"{q:#~P}"``)
+======== =================================================== ================================
diff --git a/docs/index.rst b/docs/index.rst
index 8268585..108b43e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -120,6 +120,7 @@ User Guide
     getting
     tutorial
     defining-quantities
+    formatting
     numpy
     nonmult
     log_units
diff --git a/requirements_docs.txt b/requirements_docs.txt
index c698538..450c3ce 100644
--- a/requirements_docs.txt
+++ b/requirements_docs.txt
@@ -1,3 +1,4 @@
+sphinx
 ipython
 matplotlib
 nbsphinx
@@ -7,6 +8,7 @@ pandas==1.2.4
 pint-pandas
 jupyter_client
 ipykernel
+ipython
 graphviz
 xarray
 pooch