Merge pull request #455 from skirpichev/docs

Improve sphinx documentation
aleaxit · Nov 12, 2023 · 1be5f1a · 1be5f1a
2 parents e002e2c + a3c536e
commit 1be5f1a
Show file tree

Hide file tree

Showing 12 changed files with 246 additions and 367 deletions.
diff --git a/docs/advmpz.rst b/docs/advmpz.rst
@@ -1,11 +1,8 @@
-Multiple-precision Integers (Advanced topics)
-=============================================
+Integers (Advanced topics)
+==========================
 
 .. currentmodule:: gmpy2
 
-The xmpz type
--------------
-
 gmpy2 provides access to an experimental integer type called `xmpz`. The
 `xmpz` type is a mutable integer type. In-place operations (+=, //=,
 etc.) modify the original object and do not create a new object. Instances of
@@ -124,6 +121,9 @@ prime numbers.
         print(len(result))
 
 
+The xmpz type
+-------------
+
 .. autoclass:: xmpz
    :special-members: __format__
 

diff --git a/docs/contexts.rst b/docs/contexts.rst
@@ -1,66 +1,17 @@
+.. _contexts:
+
 Contexts
 ========
 
 .. currentmodule:: gmpy2
 
-A `context` type is used to control the behavior
-of `mpfr` and `mpc` arithmetic.  In addition to controlling the
-precision, the rounding mode can be specified, minimum and maximum exponent
-values can be changed, various exceptions can be raised or ignored, gradual
-underflow can be enabled, and returning complex results can be enabled.
-
 `context()` creates a new context with all options set to default.
 `set_context()` will set the active context.  `get_context()` will
 return a reference to the active context. Note that contexts are mutable:
 modifying the reference returned by `get_context()` will modify the active
 context until a new context is enabled with `set_context()`. The
 `~context.copy()` method of a context will return a copy of the context.
 
-The following example just modifies the precision. The remaining options will
-be discussed later.
-
-.. doctest::
-
-    >>> import gmpy2
-    >>> from gmpy2 import mpfr
-    >>> gmpy2.set_context(gmpy2.context())
-    >>> gmpy2.get_context()
-    context(precision=53, real_prec=Default, imag_prec=Default,
-            round=RoundToNearest, real_round=Default, imag_round=Default,
-            emax=1073741823, emin=-1073741823,
-            subnormalize=False,
-            trap_underflow=False, underflow=False,
-            trap_overflow=False, overflow=False,
-            trap_inexact=False, inexact=False,
-            trap_invalid=False, invalid=False,
-            trap_erange=False, erange=False,
-            trap_divzero=False, divzero=False,
-            allow_complex=False,
-            rational_division=False,
-            allow_release_gil=False)
-    >>> gmpy2.sqrt(5)
-    mpfr('2.2360679774997898')
-    >>> gmpy2.get_context().precision=100
-    >>> gmpy2.sqrt(5)
-    mpfr('2.2360679774997896964091736687316',100)
-    >>> gmpy2.get_context().precision+=20
-    >>> gmpy2.sqrt(5)
-    mpfr('2.2360679774997896964091736687312762351',120)
-    >>> ctx=gmpy2.get_context()
-    >>> ctx.precision+=20
-    >>> gmpy2.sqrt(5)
-    mpfr('2.2360679774997896964091736687312762354406182',140)
-    >>> gmpy2.set_context(gmpy2.context())
-    >>> gmpy2.sqrt(5)
-    mpfr('2.2360679774997898')
-    >>> ctx.precision+=20
-    >>> gmpy2.sqrt(5)
-    mpfr('2.2360679774997898')
-    >>> gmpy2.set_context(ctx)
-    >>> gmpy2.sqrt(5)
-    mpfr('2.2360679774997896964091736687312762354406183596116',160)
-    >>> gmpy2.set_context(gmpy2.context())
-
 Context Type
 ------------
 
@@ -93,6 +44,7 @@ set to 100. When the block is finished, the original context is restored.
 
 .. doctest::
 
+    >>> import gmpy2
     >>> print(gmpy2.sqrt(2))
     1.4142135623730951
     >>> with gmpy2.local_context(gmpy2.context(), precision=100) as ctx:

diff --git a/docs/exceptions.rst b/docs/exceptions.rst
@@ -0,0 +1,11 @@
+Exceptions
+----------
+
+.. currentmodule:: gmpy2
+
+.. autoexception:: RangeError
+.. autoexception:: InexactResultError
+.. autoexception:: OverflowResultError
+.. autoexception:: UnderflowResultError
+.. autoexception:: InvalidOperationError
+.. autoexception:: DivisionByZeroError
diff --git a/docs/generic.rst b/docs/generic.rst
@@ -0,0 +1,18 @@
+Generic Functions
+-----------------
+
+.. currentmodule:: gmpy2
+
+.. autofunction:: add
+.. autofunction:: div
+.. autofunction:: mul
+.. autofunction:: sub
+
+.. autofunction:: square
+
+.. autofunction:: f2q
+
+.. autofunction:: fma
+.. autofunction:: fms
+
+.. autofunction:: cmp_abs
diff --git a/docs/index.rst b/docs/index.rst
@@ -24,14 +24,18 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   install
    overview
+   install
+   tutorial
    mpz
    advmpz
    mpq
    contexts
+   exceptions
    mpfr
    mpc
+   generic
+   misc
    cython
    conversion
    history

diff --git a/docs/misc.rst b/docs/misc.rst
@@ -0,0 +1,17 @@
+Miscellaneous Functions
+-----------------------
+
+.. currentmodule:: gmpy2
+
+.. autofunction:: digits
+.. autofunction:: from_binary
+.. autofunction:: license
+.. autofunction:: mp_limbsize
+.. autofunction:: mp_version
+.. autofunction:: mpc_version
+.. autofunction:: mpfr_version
+.. autofunction:: random_state
+.. autofunction:: to_binary
+.. autofunction:: version
+
+
diff --git a/docs/mpc.rst b/docs/mpc.rst
@@ -3,72 +3,6 @@ Multiple-precision Complex
 
 .. currentmodule:: gmpy2
 
-gmpy2 adds a multiple-precision complex type called `mpc` that is based
-on the MPC library. The context manager settings for `mpfr` arithmetic are
-applied to `mpc` arithmetic by default. It is possible to specify
-different precision and rounding modes for both the real and imaginary
-components of an `mpc`.
-
-.. doctest::
-
-    >>> import gmpy2
-    >>> from gmpy2 import mpc
-    >>> gmpy2.set_context(gmpy2.context())
-    >>> gmpy2.sqrt(mpc("1+2j"))
-    mpc('1.272019649514069+0.78615137775742328j')
-    >>> gmpy2.set_context(gmpy2.context(real_prec=60,imag_prec=70))
-    >>> gmpy2.get_context()
-    context(precision=53, real_prec=60, imag_prec=70,
-            round=RoundToNearest, real_round=Default, imag_round=Default,
-            emax=1073741823, emin=-1073741823,
-            subnormalize=False,
-            trap_underflow=False, underflow=False,
-            trap_overflow=False, overflow=False,
-            trap_inexact=False, inexact=False,
-            trap_invalid=False, invalid=False,
-            trap_erange=False, erange=False,
-            trap_divzero=False, divzero=False,
-            allow_complex=False,
-            rational_division=False,
-            allow_release_gil=False)
-    >>> gmpy2.sqrt(mpc("1+2j"))
-    mpc('1.272019649514068965+0.78615137775742328606947j',(60,70))
-    >>> gmpy2.set_context(gmpy2.context())
-
-Exceptions are normally raised in Python when the result of a real operation
-is not defined over the reals; for example, ``sqrt(-4)`` will raise an
-exception. The default context in gmpy2 implements the same behavior but by
-setting allow_complex to True, complex results will be returned.
-
-.. doctest::
-
-    >>> import gmpy2
-    >>> from gmpy2 import mpc
-    >>> gmpy2.sqrt(-4)
-    mpfr('nan')
-    >>> gmpy2.get_context().allow_complex=True
-    >>> gmpy2.sqrt(-4)
-    mpc('0.0+2.0j')
-
-The `mpc` type supports the `~mpc.__format__()` special method to
-allow custom output formatting.
-
-.. doctest::
-
-    >>> import gmpy2
-    >>> from gmpy2 import mpc
-    >>> a=gmpy2.sqrt(mpc("1+2j"))
-    >>> a
-    mpc('1.272019649514069+0.78615137775742328j')
-    >>> "{0:.4.4Mf}".format(a)
-    '(1.2720 0.7862)'
-    >>> "{0:.4.4f}".format(a)
-    '1.2720+0.7862j'
-    >>> "{0:^20.4.4U}".format(a)
-    '   1.2721+0.7862j   '
-    >>> "{0:^20.4.4D}".format(a)
-    '   1.2720+0.7861j   '
-
 mpc Type
 --------
 

diff --git a/docs/mpfr.rst b/docs/mpfr.rst
@@ -3,49 +3,6 @@ Multiple-precision Reals
 
 .. currentmodule:: gmpy2
 
-The `mpfr` type is based on the MPFR library. The new `mpfr` type supports
-correct rounding, selectable rounding modes, and many trigonometric,
-exponential, and special functions. A *context manager* is used to control
-precision, rounding modes, and the behavior of exceptions.
-
-The default precision of an `mpfr` is 53 bits - the same precision as Python's
-`float` type. If the precision is changed, then ``mpfr(float('1.2'))`` differs
-from ``mpfr('1.2')``. To take advantage of the higher precision provided by
-the `mpfr` type, always pass constants as strings.
-
-.. doctest::
-
-    >>> import gmpy2
-    >>> from gmpy2 import mpfr
-    >>> gmpy2.set_context(gmpy2.context())
-    >>> mpfr('1.2')
-    mpfr('1.2')
-    >>> mpfr(float('1.2'))
-    mpfr('1.2')
-    >>> gmpy2.get_context().precision=100
-    >>> mpfr('1.2')
-    mpfr('1.2000000000000000000000000000006',100)
-    >>> mpfr(float('1.2'))
-    mpfr('1.1999999999999999555910790149937',100)
-
-The `mpfr` type supports the `~mpfr.__format__()` special method to
-allow custom output formatting.
-
-.. doctest::
-
-    >>> from gmpy2 import mpfr
-    >>> a=mpfr("1.23456")
-    >>> "{0:15.3f}".format(a)
-    '          1.235'
-    >>> "{0:15.3Uf}".format(a)
-    '          1.235'
-    >>> "{0:15.3Df}".format(a)
-    '          1.234'
-    >>> "{0:.3Df}".format(a)
-    '1.234'
-    >>> "{0:+.3Df}".format(a)
-    '+1.234'
-
 mpfr Type
 ---------
 

diff --git a/docs/mpq.rst b/docs/mpq.rst
@@ -1,21 +1,8 @@
-Multiple-precision Rationals
-============================
+Rationals
+=========
 
 .. currentmodule:: gmpy2
 
-gmpy2 provides a rational type `mpq`. It should be a replacement for
-Python's `~fractions.Fraction` class.
-
-.. doctest::
-
-    >>> from gmpy2 import mpq
-    >>> mpq(1,7)
-    mpq(1,7)
-    >>> mpq(1,7) * 11
-    mpq(11,7)
-    >>> mpq(11,7)/13
-    mpq(11,91)
-
 mpq type
 --------
 

diff --git a/docs/mpz.rst b/docs/mpz.rst
@@ -1,38 +1,8 @@
-Multiple-precision Integers
-===========================
+Integers
+========
 
 .. currentmodule:: gmpy2
 
-The gmpy2 `mpz` type supports arbitrary precision integers. It should be a
-drop-in replacement for Python's `int` type. Depending on the platform and the
-specific operation, an `mpz` will be faster than Python's `int` once the
-precision exceeds 20 to 50 digits. All the special integer functions in GMP are
-supported.
-
-Examples
---------
-
-.. doctest::
-
-    >>> from gmpy2 import is_prime, mpz
-    >>> mpz('123') + 1
-    mpz(124)
-    >>> 10 - mpz(1)
-    mpz(9)
-    >>> is_prime(17)
-    True
-    >>> mpz('1_2')
-    mpz(12)
-
-.. note::
-    The use of ``from gmpy2 import *`` is not recommended. The names in gmpy2
-    have been chosen to avoid conflict with Python's builtin names but gmpy2
-    does use names that may conflict with other modules or variable names.
-
-.. note::
-   `mpz` ignores all embedded underscore characters. It does not attempt to be
-   100% compatible with all Python exceptions.
-
 mpz type
 --------