Doc fixes2 (#540)

* fix formatting

* constants: fix doctest

* user-api: add Time and U_, mv geometry obj to end

Fixes #526

* use pint/latest for intersphinx mapping

* add U_ top level

* add pint docs link

* apply same hack for U as Q to be included in toctree

* declare TimeDependent abc firstly.

* do not link TimeDependent here

Co-authored-by: Cagtay Fabry <[email protected]>

doc/conf.py

@@ -273,7 +273,7 @@ def _prevent_sphinx_circular_imports_bug():
     "matplotlib": ("https://matplotlib.org", None),
     # "dask": ("https://docs.dask.org/en/latest", None),
     # "numba": ("https://numba.pydata.org/numba-doc/latest", None),
-    "pint": ("https://pint.readthedocs.io/en/stable", None),
+    "pint": ("https://pint.readthedocs.io/en/latest", None),
     "jsonschema": ("https://python-jsonschema.readthedocs.io/en/stable/", None),
     "asdf": ("https://asdf.readthedocs.io/en/latest/", None),
     "networkx": ("https://networkx.org/documentation/stable/", None),

weldx/__init__.py

@@ -30,6 +30,19 @@
     GmawProcess
     get_groove
 
+**Data handling and transformation**
+
+.. autosummary::
+    :toctree: _autosummary
+    :caption: Data handling and transformation
+    :template: class-template.rst
+
+    Q_
+    U_
+    Time
+    TimeSeries
+    CoordinateSystemManager
+    LocalCoordinateSystem
 
 **Geometry**
 
@@ -49,19 +62,6 @@
     Trace
     SpatialData
 
-
-**Data handling and transformation**
-
-.. autosummary::
-    :toctree: _autosummary
-    :caption: Data handling and transformation
-    :template: class-template.rst
-
-    Q_
-    TimeSeries
-    CoordinateSystemManager
-    LocalCoordinateSystem
-
 **Full API Reference**
 
 Here you find the full documentation for all sub-modules in weldx
@@ -116,7 +116,7 @@
     )
 
 # constants - should be imported first, no internal weldx deps
-from .constants import Q_
+from .constants import Q_, U_
 
 # main modules
 import weldx.time
@@ -166,6 +166,7 @@
     "LocalCoordinateSystem",
     "Profile",
     "Q_",
+    "U_",
     "Shape",
     "SpatialData",
     "Trace",

weldx/constants.py

@@ -26,23 +26,35 @@
 Q_.__doc__ = """Create a quantity from a scalar or array.
 
 The quantity class supports lots of physical units and will combine them during
-mathematical operations
+mathematical operations.
+For extended details on working with quantities, please see the
+`pint documentation <http://https://pint.readthedocs.io/>`_
 
 Examples
 --------
 >>> from weldx import Q_
 >>> length = Q_(10, "mm")
 >>> length
+<Quantity(10, 'millimeter')>
 
 define a time:
+
 >>> time = Q_(1, "s")
 >>> time
+<Quantity(1, 'second')>
 
 lets combine length and time to get a velocity.
+
 >>> v = length / time
 >>> v
+<Quantity(10.0, 'millimeter / second')>
 """
+__test__ = {"Q": Q_.__doc__}  # enable doctest checking.
+
 U_ = WELDX_UNIT_REGISTRY.Unit
+U_.__name__ = "U_"
+U_.__module__ = "pint.unit"  # skipcq: PYL-W0212
+
 
 __all__ = (
     "WELDX_PATH",

weldx/time.py

@@ -26,6 +26,20 @@
 ]
 
 
+class TimeDependent(ABC):
+    """An abstract base class that describes a common interface of time dep. classes."""
+
+    @property
+    @abstractmethod
+    def time(self) -> Time:
+        """Get the classes time component."""
+
+    @property
+    @abstractmethod
+    def reference_time(self) -> Union[Timestamp, None]:
+        """Return the reference timestamp if the time data is absolute."""
+
+
 class Time:
     """Provides a unified interface for time related operations.
 
@@ -130,7 +144,7 @@ class 'TimeDependent' are supported too.
     >>> t_abs = Time("2014-07-23")
     >>> t_abs = Time(["2000","2001","2002"])
 
-    Types that are derived from the abstract base class `TimeDependent` can also be
+    Types that are derived from the abstract base class ``TimeDependent`` can also be
     passed directly to `Time` as `time` parameter:
 
     >>> from weldx import LocalCoordinateSystem as LCS
@@ -654,20 +668,6 @@ def _union_instance(self, times: Sequence[types_time_like]) -> Time:
         return Time._union_class([self, *times])
 
 
-class TimeDependent(ABC):
-    """An abstract base class that describes a common interface of time dep. classes."""
-
-    @property
-    @abstractmethod
-    def time(self) -> Time:
-        """Get the classes time component."""
-
-    @property
-    @abstractmethod
-    def reference_time(self) -> Union[Timestamp, None]:
-        """Return the reference timestamp if the time data is absolute."""
-
-
 # list of types that are supported to be stored in Time._time
 _data_base_types = (pd.Timedelta, pd.Timestamp, pd.DatetimeIndex, pd.TimedeltaIndex)