Merge pull request #1638 from hgrecco/develop

Improved the API documentation to avoid breaking intersphinx
hgrecco · Oct 27, 2022 · 7e82013 · 7e82013
2 parents cf1a802 + 52b616e
commit 7e82013
Show file tree

Hide file tree

Showing 31 changed files with 463 additions and 200 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -154,7 +154,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: [3.8, 3.9, "3.10", "3.11"]
-        numpy: [ "numpy>=1.19,<2.0.0" ]
+        numpy: [null, "numpy>=1.19,<2.0.0" ]
     runs-on: macos-latest
 
     env:

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,70 @@
+
+Base API
+========
+
+.. currentmodule:: pint
+
+
+These are the classes, exceptions and functions that you will most likely use.
+
+
+Most important classes
+----------------------
+
+.. autoclass:: UnitRegistry
+    :members:
+    :exclude-members: Quantity, Unit, Measurement, Group, Context, System
+
+.. autoclass:: Quantity
+    :members:
+    :inherited-members:
+
+.. autoclass:: Unit
+    :members:
+    :inherited-members:
+
+.. autoclass:: Measurement
+    :members:
+    :inherited-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/facets.rst b/docs/api/facets.rst
@@ -0,0 +1,45 @@
+API facets reference
+====================
+
+Registry functionality is divided into facet. Each provides classes and functions
+specific to a particular purpose. They expose at least a Registry, and in certain
+cases also a Quantity, Unit and other objects.
+
+The default UnitRegistry inherits from all of them.
+
+
+.. 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
+    specific
+    facets
diff --git a/docs/api/specific.rst b/docs/api/specific.rst
@@ -0,0 +1,44 @@
+Specific API
+============
+
+These are the classes, exceptions and functions that you will use if you need
+to dig deeper into Pint or develop Pint.
+
+
+.. 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/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