Doc updates, make class references working links, fuss with some examples, update copyright

Author: Tim Bielawa

docsite/source/classes.rst

@@ -119,7 +119,7 @@ Initializing
 
    :param int value: **Default: 0**. The value of the instance in
                      *prefix units*. For example, if we were
-                     instantiating a ``bitmath.KiB`` object to
+                     instantiating a :class:`.KiB` object to
                      represent 13.37 KiB, the ``value`` parameter
                      would be **13.37**. For instance, ``k =
                      bitmath.KiB(13.37)``.
@@ -163,8 +163,8 @@ Class Method: from_other()
 ==========================
 
 bitmath **class objects** have one public class method,
-:py:meth:`BitMathClass.from_other` which provides an
-alternative way to initialize a bitmath class.
+:py:meth:`.from_other` which provides an alternative way to initialize
+a bitmath class.
 
 This method may be called on bitmath class objects directly. That is
 to say: you do not need to call this method on an instance of a
@@ -176,8 +176,8 @@ bitmath class, however that is a valid use case.
    Instantiate any ``BitMathClass`` using another instance as
    reference for it's initial value.
 
-   The ``from_other()`` class method has one required parameter: an
-   instance of a bitmath class.
+   The :py:meth:`.from_other` class method has one required parameter:
+   an instance of a bitmath class.
 
    :param BitMathInstance item: An instance of a bitmath class.
    :return: a bitmath instance of type ``BitMathClass`` equivalent in
@@ -204,7 +204,7 @@ bitmath class, however that is a valid use case.
       >>> print(a_mebibyte, a_mebibyte_sized_kibibyte)
       1.0 MiB 1024.0 KiB
 
-   Or, using the :py:meth:`BitMathClass.from_other` class method:
+   Or, using the :py:meth:`.from_other` class method:
 
    .. code-block:: python
       :linenos:

docsite/source/conf.py

@@ -48,7 +48,7 @@
 
 # General information about the project.
 project = u'bitmath'
-copyright = u'2014-2016, Tim Bielawa'
+copyright = u'2014-2023, Tim Bielawa'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docsite/source/conf.py.in

@@ -48,7 +48,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'bitmath'
-copyright = u'2014-2016, Tim Bielawa'
+copyright = u'2014-2023, Tim Bielawa'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docsite/source/index.rst

@@ -72,50 +72,32 @@ yourself <https://github.com/tbielawa/bitmath/tree/master/tests>`_.
 Installation
 ############
 
-The easiest way to install bitmath is via ``dnf`` (or ``yum``) if
-you're on a Fedora/RHEL based distribution. bitmath is available in
-the main Fedora repositories, as well as EPEL Repositories. As of 2023
-bitmath is only developed, tested, and supported for `currently
-supported <https://devguide.python.org/versions/>`_ Python releases.
+bitmath is available in Fedora and EPEL repositories, as well as
+directly available via `PyPI
+<https://pypi.python.org/pypi/bitmath>`_. As of 2023 bitmath is only
+developed, tested, and supported for `currently supported
+<https://devguide.python.org/versions/>`_ Python releases.
 
+**Package Managers**
 
 .. code-block:: bash
 
    $ sudo dnf install python3-bitmath
+   $ pip install --user bitmath
 
 
-**PyPi**:
+**Source**::
 
-You could also install bitmath from `PyPi
-<https://pypi.python.org/pypi/bitmath>`_ if you like:
-
-.. code-block:: bash
-
-   $ sudo pip install bitmath
-
-.. note::
-
-   **pip** installs need pip >= 1.1. To workaround this, `download
-   bitmath <https://pypi.python.org/pypi/bitmath/#downloads>`_, from
-   PyPi and then ``pip install bitmath-x.y.z.tar.gz``. See `issue #57
-   <https://github.com/tbielawa/bitmath/issues/57#issuecomment-227018168>`_
-   for more information.
-
-
-
-**Source**:
+    NOTE: UPDATE THIS FOR THE NEW HATCH.TOML THING
 
 Or, if you want to install from source:
 
 .. code-block:: bash
 
    $ sudo python ./setup.py install
 
-If you want the bitmath manpage installed as well:
-
-.. code-block:: bash
-
-   $ sudo make install
+If you want the ``/bin/bitmath`` manpage too, then ``sudo make
+install`` will install the Python library and the manpage.
 
 
 Contents

docsite/source/index.rst.in

@@ -72,50 +72,32 @@ yourself <https://github.com/tbielawa/bitmath/tree/master/tests>`_.
 Installation
 ############
 
-The easiest way to install bitmath is via ``dnf`` (or ``yum``) if
-you're on a Fedora/RHEL based distribution. bitmath is available in
-the main Fedora repositories, as well as EPEL Repositories. As of 2023
-bitmath is only developed, tested, and supported for `currently
-supported <https://devguide.python.org/versions/>`_ Python releases.
+bitmath is available in Fedora and EPEL repositories, as well as
+directly available via `PyPI
+<https://pypi.python.org/pypi/bitmath>`_. As of 2023 bitmath is only
+developed, tested, and supported for `currently supported
+<https://devguide.python.org/versions/>`_ Python releases.
 
+**Package Managers**
 
 .. code-block:: bash
 
    $ sudo dnf install python3-bitmath
+   $ pip install --user bitmath
 
 
-**PyPi**:
+**Source**::
 
-You could also install bitmath from `PyPi
-<https://pypi.python.org/pypi/bitmath>`_ if you like:
-
-.. code-block:: bash
-
-   $ sudo pip install bitmath
-
-.. note::
-
-   **pip** installs need pip >= 1.1. To workaround this, `download
-   bitmath <https://pypi.python.org/pypi/bitmath/#downloads>`_, from
-   PyPi and then ``pip install bitmath-x.y.z.tar.gz``. See `issue #57
-   <https://github.com/tbielawa/bitmath/issues/57#issuecomment-227018168>`_
-   for more information.
-
-
-
-**Source**:
+    NOTE: UPDATE THIS FOR THE NEW HATCH.TOML THING
 
 Or, if you want to install from source:
 
 .. code-block:: bash
 
    $ sudo python ./setup.py install
 
-If you want the bitmath manpage installed as well:
-
-.. code-block:: bash
-
-   $ sudo make install
+If you want the ``/bin/bitmath`` manpage too, then ``sudo make
+install`` will install the Python library and the manpage.
 
 
 Contents

docsite/source/instances.rst

@@ -21,9 +21,10 @@ bitmath objects have several instance attributes:
 
    .. code-block:: python
 
-      >>> b = bitmath.Byte(1337)
-      >>> print(b.base)
+      >>> print(bitmath.Byte(1337).base)
       2
+      >>> print(bitmath.kB(1337).base)
+      10
 
 .. py:attribute:: BitMathInstance.binary
 

docsite/source/module.rst

@@ -30,7 +30,7 @@ bitmath.getsize()
    :param bool bestprefix: **Default:** ``True``, the returned
                            instance will be in the best human-readable
                            prefix unit. If set to ``False`` the result
-                           is a ``bitmath.Byte`` instance.
+                           is a :class:`.Byte` instance.
    :param system: **Default:** :py:data:`bitmath.NIST`. The preferred
                   system of units for the returned instance.
    :type system: One of :py:data:`bitmath.NIST` or :py:data:`bitmath.SI`
@@ -110,7 +110,7 @@ bitmath.listdir()
                         :py:func:`os.path.realpath` to normalize path
                         references
    :param bool bestprefix: **Default:** ``False``, returns
-                           ``bitmath.Byte`` instances. Set to ``True``
+                           :class:`.Byte` instances. Set to ``True``
                            to return the best human-readable prefix
                            unit for representation
    :param system: **Default:** :py:data:`bitmath.NIST`. Set a prefix
@@ -123,7 +123,7 @@ bitmath.listdir()
       * This function does **not** return tuples for directory
         entities. Including directories in results is `scheduled for
         introduction <https://github.com/tbielawa/bitmath/issues/27>`_
-        in the upcoming 1.1.0 release.
+        in an upcoming release.
       * Symlinks to **files** are followed automatically
 
 
@@ -224,8 +224,6 @@ bitmath.parse_string()
 
 .. function:: parse_string(str_repr)
 
-   .. versionadded:: 1.1.0
-
    Parse a string representing a unit into a proper bitmath
    object. All non-string inputs are rejected and will raise a
    :py:exc:`ValueError`. Strings without units are also rejected. See
@@ -337,14 +335,14 @@ bitmath.parse_string()
       forgiving with input. Please read the documentation carefully so
       you understand the risks you assume using the ``unsafe`` parser.
 
+   .. versionadded:: 1.1.0
+
 
 bitmath.parse_string_unsafe()
 =============================
 
 .. function:: parse_string_unsafe(repr[, system=bitmath.SI])
 
-   .. versionadded:: 1.3.1
-
    Parse a string or number into a proper bitmath object. This is the
    less strict version of the :py:func:`bitmath.parse_string`
    function. While :py:func:`bitmath.parse_string` only accepts SI and
@@ -472,6 +470,7 @@ bitmath.parse_string_unsafe()
    Capital **G** followed by a lower-case **i** ending with a capital
    **B**, ``GiB``.
 
+   .. versionadded:: 1.3.1
 
 
 bitmath.query_device_capacity()

docsite/source/real_life_examples.rst

@@ -411,17 +411,6 @@ object with the ``query_device_capacity`` function. Here's an example
 where we read the capacity of device ``sda``, the first device on the
 example system.
 
-.. code-block:: python
-
-   >>> import bitmath
-   >>> fh = open('/dev/sda', 'r')
-   >>> sda_capacity = bitmath.query_device_capacity(fh)
-   >>> fh.close()
-   >>> print(sda_capacity.best_prefix())
-   238.474937439 GiB
-
-We can simplify this so that the file handle is automatically closed
-for us by using the ``with`` context manager.
 
 .. code-block:: python