From 94314ed80883b3d6a261f7e5a23ab11773bb0e6c Mon Sep 17 00:00:00 2001
From: Eduardo Rodrigues <eduardo.rodrigues@cern.ch>
Date: Wed, 13 Oct 2021 13:33:30 +0200
Subject: [PATCH] Better documentation via help(...) (#48)

* Better documentation via help(...)

* Minor update
---
 src/hepunits/constants/__init__.py  | 21 ---------------------
 src/hepunits/constants/constants.py | 19 ++++++++++++++++++-
 src/hepunits/units/__init__.py      |  8 --------
 src/hepunits/units/prefixes.py      |  3 +--
 src/hepunits/units/units.py         | 14 +++++++++-----
 5 files changed, 28 insertions(+), 37 deletions(-)

diff --git a/src/hepunits/constants/__init__.py b/src/hepunits/constants/__init__.py
index 2227b1d..2a5d84c 100644
--- a/src/hepunits/constants/__init__.py
+++ b/src/hepunits/constants/__init__.py
@@ -1,25 +1,4 @@
 # -*- coding: utf-8 -*-
 # Licensed under a 3-clause BSD style license, see LICENSE.
-"""
-This module `hepunits.constants` contains 2 sorts of constants:
-
-  * Physical constants.
-  * Common and/or handy constants.
-
-All constants are computed in the HEP System of Units
-as defined in the `hepunits.units` package.
-
-Typical use case::
-
-    >>> from hepunits.constants import c_light
-    >>> from hepunits.units     import picosecond, micrometer
-    >>> tau_Bs = 1.5 * picosecond    # a particle lifetime, say the Bs meson's
-    >>> ctau_Bs = c_light * tau_Bs   # ctau of the particle, ~450 microns
-    >>> print ctau_Bs                # result in HEP units, so mm ;-)
-    0.449688687
-    >>> print ctau_Bs / micrometer   # result in micrometers
-    449.688687
-
-"""
 
 from .constants import *
diff --git a/src/hepunits/constants/constants.py b/src/hepunits/constants/constants.py
index 6e31ce5..8d082f1 100644
--- a/src/hepunits/constants/constants.py
+++ b/src/hepunits/constants/constants.py
@@ -4,8 +4,25 @@
 Physical and other handy constants
 ==================================
 
+This module `hepunits.constants` contains 2 sorts of constants:
+
+  * Physical constants.
+  * Common and/or handy constants.
+
 All constants are computed in the HEP System of Units
-as defined in the units module.
+as defined in the `hepunits.units` module.
+
+Typical use case::
+
+    >>> from hepunits.constants import c_light
+    >>> from hepunits.units     import picosecond, micrometer
+    >>> tau_Bs = 1.5 * picosecond    # a particle lifetime, say the Bs meson's
+    >>> ctau_Bs = c_light * tau_Bs   # ctau of the particle, ~450 microns
+    >>> print ctau_Bs                # result in HEP units, so mm ;-)
+    0.449688687
+    >>> print ctau_Bs / micrometer   # result in micrometers
+    449.688687
+
 """
 
 # -----------------------------------------------------------------------------
diff --git a/src/hepunits/units/__init__.py b/src/hepunits/units/__init__.py
index 7045340..b47a232 100644
--- a/src/hepunits/units/__init__.py
+++ b/src/hepunits/units/__init__.py
@@ -1,13 +1,5 @@
 # -*- coding: utf-8 -*-
 # Licensed under a 3-clause BSD style license, see LICENSE.
 
-"""
-Subpackage for the HEP System of Units, (derived) physical units and
-commonly-used unit prefixes.
-
-The HEP System of Units is the set of basic units originally defined by the
-CLHEP project.
-"""
-
 from .prefixes import *
 from .units import *
diff --git a/src/hepunits/units/prefixes.py b/src/hepunits/units/prefixes.py
index 1cb1b17..a52933c 100644
--- a/src/hepunits/units/prefixes.py
+++ b/src/hepunits/units/prefixes.py
@@ -1,9 +1,8 @@
 # -*- coding: utf-8 -*-
 # Licensed under a 3-clause BSD style license, see LICENSE.
 """
-********************
 Common unit prefixes
-********************
+====================
 
 There are 2 types of prefixes:
 
diff --git a/src/hepunits/units/units.py b/src/hepunits/units/units.py
index 0b1cf54..fd44b66 100644
--- a/src/hepunits/units/units.py
+++ b/src/hepunits/units/units.py
@@ -2,9 +2,15 @@
 # Licensed under a 3-clause BSD style license, see LICENSE.
 
 """
-*************************
-Module of HEP basic units
-*************************
+Units in the HEP system of units
+================================
+
+This module `hepunits.units` contains 2 submodules for:
+
+  * Basic physical units and derived units (`hepunits.units.units`).
+  * Commonly-used unit prefixes (`hepunits.units.prefixes`).
+
+All units are provided in the HEP System of Units as defined below.
 
 In HEP the System of Units consists of the basic units originally defined by
 the [CLHEP]_ project:
@@ -40,8 +46,6 @@
 but augments it with handy definitions, changing the basic length and time
 units.
 
-This module also defines an extensive set of derived units.
-
 Typical use cases::
 
     >>> # add two quantities with length units and get the result in meters