first draft of the format docs

3 files changed, 80 insertions, 0 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 67e156c..47d8886 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.
diff --git a/docs/formatting.rst b/docs/formatting.rst
new file mode 100644
index 0000000..85c26f2
--- /dev/null
+++ b/docs/formatting.rst
@@ -0,0 +1,77 @@
+.. _formatting:
+.. currentmodule:: pint
+
+
+.. ipython:: python
+   :suppress:
+
+   import pint
+
+
+String formatting
+=================
+A :doc:`format specification <formatspec>` used to format :py:class:`Unit` objects in
+e.g. f-strings consists of a ``type`` and optionally a "modifier", where the order does
+not matter. For example, ``P~`` and ``~P`` have the same effect. If the ``type`` is
+omitted, or when using the :py:class:`str` builtin, the object's
+:py:attr:`Unit.default_format` property is used, falling back to
+:py:attr:`UnitRegistry.default_format` if that is not set. If both are unset, the
+default format (``"D"``) is used.
+
+.. note::
+
+   Modifiers may still be used without specifying the type: ``"~"`` is a valid format
+   specification.
+
+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
+   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
+
+**TODO**: describe quantity formats
+
+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 Formats
+----------------
+
+Modifiers
+---------
+======== =============== ============================
+Modifier Description     Example
+======== =============== ============================
+``~``    Short unit name ``kg·m/s²`` (Format: ``~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