Partially reorganized docs

- api is now split into 3 parts - files are reorganized in folders Additionally, some class members (Quantity, Unit, Measurement, Group, Context, System) are excluded from the docs as they confuse sphinx.
hgrecco · Oct 27, 2022 · cf3d431 · cf3d431
1 parent 12db799
commit cf3d431
Show file tree

Hide file tree

Showing 30 changed files with 446 additions and 198 deletions.
diff --git a/docs/user/currencies.rst → docs/advanced/currencies.rst b/docs/user/currencies.rst → docs/advanced/currencies.rst
diff --git a/docs/user/custom-registry-class.rst → docs/advanced/custom-registry-class.rst b/docs/user/custom-registry-class.rst → docs/advanced/custom-registry-class.rst
diff --git a/docs/user/defining.rst → docs/advanced/defining.rst b/docs/user/defining.rst → docs/advanced/defining.rst
diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
@@ -0,0 +1,17 @@
+Advanced Guides
+===============
+
+Pint contains some useful and fun feature. You will find them here.
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    performance
+    serialization
+    defining
+    wrapping
+    measurement
+    pitheorem
+    currencies
+    custom-registry-class
diff --git a/docs/user/measurement.rst → docs/advanced/measurement.rst b/docs/user/measurement.rst → docs/advanced/measurement.rst
diff --git a/docs/user/performance.rst → docs/advanced/performance.rst b/docs/user/performance.rst → docs/advanced/performance.rst
diff --git a/docs/user/pitheorem.rst → docs/advanced/pitheorem.rst b/docs/user/pitheorem.rst → docs/advanced/pitheorem.rst
diff --git a/docs/user/serialization.rst → docs/advanced/serialization.rst b/docs/user/serialization.rst → docs/advanced/serialization.rst
@@ -1,5 +1,3 @@
-.. _serialization:
-
 
 Serialization
 =============

diff --git a/docs/user/wrapping.rst → docs/advanced/wrapping.rst b/docs/user/wrapping.rst → docs/advanced/wrapping.rst
diff --git a/docs/advanced_guides.rst b/docs/advanced_guides.rst
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/api/base.rst b/docs/api/base.rst
@@ -0,0 +1,65 @@
+
+Base API
+========
+
+.. currentmodule:: pint
+
+
+Most important classes
+----------------------
+
+.. autoclass:: UnitRegistry
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. autoclass:: Quantity
+    :members:
+
+.. autoclass:: Unit
+    :members:
+
+.. autoclass:: Measurement
+    :members:
+
+
+Exceptions and warnings
+-----------------------
+
+.. autoexception:: PintError
+    :members:
+
+.. autoexception:: DefinitionSyntaxError
+    :members:
+
+.. autoexception:: LogarithmicUnitCalculusError
+    :members:
+
+.. autoexception:: DimensionalityError
+    :members:
+
+.. autoexception:: OffsetUnitCalculusError
+    :members:
+
+.. autoexception:: RedefinitionError
+    :members:
+
+.. autoexception:: UndefinedUnitError
+    :members:
+
+.. autoexception:: UnitStrippedWarning
+    :members:
+
+
+Sharing registry among packages
+-------------------------------
+,
+.. autofunction:: get_application_registry
+.. autofunction:: set_application_registry
+
+Other functions
+---------------
+
+.. autofunction:: formatter
+.. autofunction:: register_unit_format
+.. autofunction:: pi_theorem
+.. autoclass:: Context
diff --git a/docs/api/common.rst b/docs/api/common.rst
@@ -0,0 +1,40 @@
+Common API
+==========
+
+.. automodule:: pint.babel_names
+    :members:
+
+.. automodule:: pint.compat
+    :members:
+
+.. automodule:: pint.converters
+    :members:
+
+.. automodule:: pint.definitions
+    :members:
+
+.. automodule:: pint.errors
+    :members:
+
+.. automodule:: pint.formatting
+    :members:
+
+.. automodule:: pint.matplotlib
+    :members:
+
+.. automodule:: pint.pint_eval
+    :members:
+
+.. automodule:: pint.registry
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System, UnitRegistry
+
+.. automodule:: pint.registry_helpers
+    :members:
+
+.. automodule:: pint.testing
+    :members:
+
+.. automodule:: pint.util
+    :members:
+    :exclude-members: Unit
diff --git a/docs/api/facets.rst b/docs/api/facets.rst
@@ -0,0 +1,39 @@
+API facets reference
+====================
+
+
+.. automodule:: pint.facets.plain
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.nonmultiplicative
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.formatting
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.numpy
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.dask
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.measurement
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.group
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.system
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. automodule:: pint.facets.context
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,10 @@
+API reference
+==============
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    base
+    common
+    facets
diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst
@@ -107,15 +107,16 @@ Extension Packages
 ------------------
 
 Pint naturally integrates with other libraries in the scientific Python ecosystem, and
-a small number of
-`extension/compatibility packages<numpy.html#Compatibility-Packages>`_ have arisen to
-aid in compatibility between certain packages. Pint's rule of thumb for integration
+a small _`ecosystem` have arisen to aid in compatibility between certain packages
+allowing to build an
+
+Pint's rule of thumb for integration
 features that work best as an extension package versus direct inclusion in Pint is:
 
 * Extension (separate packages)
 
-  * Duck array types that wrap Pint (come above Pint in
-    `the type casting hierarchy<numpy.html#Technical-Commentary>`_)
+  * Duck array types that wrap Pint (come above Pint
+    in :ref:`the type casting hierarchy <_numpy#technical-commentary>`
 
   * Uses features independent/on top of the libraries
 
@@ -143,3 +144,4 @@ features that work best as an extension package versus direct inclusion in Pint
 .. _flake8: https://flake8.pycqa.org/en/latest/
 .. _pytest: https://docs.pytest.org/en/stable/
 .. _sphinx: https://www.sphinx-doc.org/en/master/
+.. _`extension/compatibility packages`:
diff --git a/docs/user/ecosystem.rst → docs/ecosystem.rst b/docs/user/ecosystem.rst → docs/ecosystem.rst
diff --git a/docs/user/faq.rst → docs/getting/faq.rst b/docs/user/faq.rst → docs/getting/faq.rst
diff --git a/docs/getting_started.rst → docs/getting/index.rst b/docs/getting_started.rst → docs/getting/index.rst
@@ -45,6 +45,7 @@ That's all! You can check that Pint is correctly installed by starting up python
     :maxdepth: 2
     :hidden:
 
-    user/overview
-    user/tutorial
-    user/faq
+    overview
+    tutorial
+    pint-in-your-projects
+    faq
diff --git a/docs/user/overview.rst → docs/getting/overview.rst b/docs/user/overview.rst → docs/getting/overview.rst
diff --git a/docs/getting/pint-in-your-projects.rst b/docs/getting/pint-in-your-projects.rst
@@ -0,0 +1,70 @@
+.. _pint_in_your_projects:
+
+Using Pint in your projects
+===========================
+
+Having a shared registry
+------------------------
+
+If you use Pint in multiple modules within your Python package, you normally
+want to avoid creating multiple instances of the unit registry.
+The best way to do this is by instantiating the registry in a single place. For
+example, you can add the following code to your package ``__init__.py``
+
+.. doctest::
+
+   >>> from pint import UnitRegistry
+   >>> ureg = UnitRegistry()
+   >>> Q_ = ureg.Quantity
+
+
+Then in ``yourmodule.py`` the code would be
+
+.. code-block:: python
+
+   from . import ureg, Q_
+
+   length = 10 * ureg.meter
+   my_speed = Q_(20, 'm/s')
+
+If you are pickling and unpickling Quantities within your project, you should
+also define the registry as the application registry
+
+.. code-block:: python
+
+   from pint import UnitRegistry, set_application_registry
+   ureg = UnitRegistry()
+   set_application_registry(ureg)
+
+
+.. warning:: There are no global units in Pint. All units belong to a registry and
+    you can have multiple registries instantiated at the same time. However, you
+    are not supposed to operate between quantities that belong to different registries.
+    Never do things like this:
+
+.. doctest::
+
+   >>> q1 = 10 * UnitRegistry().meter
+   >>> q2 = 10 * UnitRegistry().meter
+   >>> q1 + q2
+   Traceback (most recent call last):
+   ...
+   ValueError: Cannot operate with Quantity and Quantity of different registries.
+   >>> id(q1._REGISTRY) == id(q2._REGISTRY)
+   False
+
+
+Keeping up to date with Pint development
+----------------------------------------
+
+While we work hard to avoid breaking code using Pint, sometimes it
+happens. To help you track how Pint is evolving it is recommended
+that you run a daily or weekly job against pint master branch.
+
+For example, this is how xarray_ is doing it:
+
+If a new version of Pint breaks your code, please open an issue_ to
+let us know.
+
+.. _xarray: https://github.com/pydata/xarray/blob/main/.github/workflows/upstream-dev-ci.yaml
+.. _issue: https://github.com/hgrecco/pint/issues