documentation updates

- add installation instructions to docs
- advertise supported Python versions
- various reST fixes

CHANGES

@@ -2,6 +2,12 @@
  CHANGELOG for numkit
 ======================
 
+2021-07-??      1.2.1
+orbeckst
+
+* documentation updates
+
+
 2021-07-20      1.2.0
 theavey, orbeckst
 

README.rst

@@ -27,10 +27,11 @@ https://github.com/Becksteinlab/numkit ::
 
   git clone https://github.com/Becksteinlab/numkit
 
-Python 3
-========
+Python 2/3
+==========
 
-Python 3 support for this package is in alpha state
+Python 2.7 is still supported. Python 3 support for releases 3.6 - 3.9
+is tested.
 
 
 Contributing

docs/source/conf.py

@@ -37,12 +37,12 @@
 
 # General substitutions.
 project = u'numkit'
-copyright = u'2009-2018, The Authors of numkit (see AUTHORS)'
+copyright = u'2009-2021, The Authors of numkit (see AUTHORS)'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
-packageversion = "1.1.2"
+packageversion = "1.2.0"
 
 # The short X.Y version.
 version = '.'.join(packageversion.split('.')[:2])

docs/source/index.txt

@@ -40,7 +40,8 @@ Contents
 
 .. toctree::
    :maxdepth: 1
-
+
+   installation
    src
    fitting
    timeseries

docs/source/installation.txt

@@ -0,0 +1,15 @@
+==============
+ Installation
+==============
+
+You can install from :ref:`source-code` or with :program:`pip` from
+the `numkit PyPi repository`_ with ::
+
+  pip install numkit
+
+Python 2.7 and recent Python 3 are all supported.
+
+
+
+.. _numkit PyPi repository: https://pypi.org/project/numkit/
+

docs/source/src.txt

@@ -1,3 +1,5 @@
+.. _source-code:
+
 =============
  Source Code
 =============
@@ -14,6 +16,10 @@ Get the sources with ::
 
   git clone https://github.com/Becksteinlab/numkit
 
+and install with ::
+
+  pip install ./numkit
+
 
 Contributing
 ------------

src/numkit/observables.py

@@ -8,6 +8,8 @@
 class QID(frozenset):
     """Identity of a :class:`QuantityWithError`.
 
+    The basic idea::
+
       QID(iterable) --> identity
       QID() --> ``None``
 
@@ -110,25 +112,30 @@ def isSame(self, other):
         """Check if *other* is 100% correlated with *self*.
 
         ``True`` if
-          `- *other* is the same observable (instance)
+
+           - *other* is the same observable (instance)
            - *other* was derived from *self* without using any
              other independent quantities with errors, e.g. ::
+
                 >>> a = QuantityWithError(1.0, 0.5)
                 >>> b = a**2 - a*2
                 >>> a.isSame(b)
                 True
 
         ``False`` if
+
             - *other* is a scalar (without an error), or
             - *other* was computed from *self* without involvement of
               any other observables.
 
-        :TODO: How should one treat the case when a quantity is used
-               again in an operation, e.g.  ::
-                 c = a + b
-                 d = c/a
-               How to compute the error on d? What should the result
-               for ``c.isSame(a)`` be?
+        **Limitations**: How should one treat the case when a quantity is used
+        again in an operation, e.g.  ::
+
+           c = a + b
+           d = c/a
+
+        How to compute the error on d? What should the result
+        for ``c.isSame(a)`` be?
         """
         try:
             return self.qid == other.qid