diff --git a/src/doc/common/_vendor/cvxopt.inv b/src/doc/common/_vendor/cvxopt.inv new file mode 100644 index 00000000000..18438ed5381 Binary files /dev/null and b/src/doc/common/_vendor/cvxopt.inv differ diff --git a/src/doc/common/_vendor/cvxpy.inv b/src/doc/common/_vendor/cvxpy.inv new file mode 100644 index 00000000000..33eabf78f40 Binary files /dev/null and b/src/doc/common/_vendor/cvxpy.inv differ diff --git a/src/doc/common/_vendor/cypari2.inv b/src/doc/common/_vendor/cypari2.inv new file mode 100644 index 00000000000..8f4ad4acb98 Binary files /dev/null and b/src/doc/common/_vendor/cypari2.inv differ diff --git a/src/doc/common/_vendor/cysignals.inv b/src/doc/common/_vendor/cysignals.inv new file mode 100644 index 00000000000..b0f2bbcef2f Binary files /dev/null and b/src/doc/common/_vendor/cysignals.inv differ diff --git a/src/doc/common/_vendor/flint.inv b/src/doc/common/_vendor/flint.inv new file mode 100644 index 00000000000..099c465fa90 Binary files /dev/null and b/src/doc/common/_vendor/flint.inv differ diff --git a/src/doc/common/_vendor/fpylll.inv b/src/doc/common/_vendor/fpylll.inv new file mode 100644 index 00000000000..aca64880a23 Binary files /dev/null and b/src/doc/common/_vendor/fpylll.inv differ diff --git a/src/doc/common/_vendor/gmpy2.inv b/src/doc/common/_vendor/gmpy2.inv new file mode 100644 index 00000000000..c91bc5ccdf5 Binary files /dev/null and b/src/doc/common/_vendor/gmpy2.inv differ diff --git a/src/doc/common/_vendor/ipywidgets.inv b/src/doc/common/_vendor/ipywidgets.inv new file mode 100644 index 00000000000..745e1f94c49 Binary files /dev/null and b/src/doc/common/_vendor/ipywidgets.inv differ diff --git a/src/doc/common/_vendor/matplotlib.inv b/src/doc/common/_vendor/matplotlib.inv new file mode 100644 index 00000000000..0b0d8f47401 Binary files /dev/null and b/src/doc/common/_vendor/matplotlib.inv differ diff --git a/src/doc/common/_vendor/mpmath.inv b/src/doc/common/_vendor/mpmath.inv new file mode 100644 index 00000000000..c6cfdd89ff4 Binary files /dev/null and b/src/doc/common/_vendor/mpmath.inv differ diff --git a/src/doc/common/_vendor/networkx.inv b/src/doc/common/_vendor/networkx.inv new file mode 100644 index 00000000000..4d38bd31edd Binary files /dev/null and b/src/doc/common/_vendor/networkx.inv differ diff --git a/src/doc/common/_vendor/numpy.inv b/src/doc/common/_vendor/numpy.inv new file mode 100644 index 00000000000..e5909cfe190 Binary files /dev/null and b/src/doc/common/_vendor/numpy.inv differ diff --git a/src/doc/common/_vendor/pplpy.inv b/src/doc/common/_vendor/pplpy.inv new file mode 100644 index 00000000000..ecc4ffaccd0 Binary files /dev/null and b/src/doc/common/_vendor/pplpy.inv differ diff --git a/src/doc/common/_vendor/python.inv b/src/doc/common/_vendor/python.inv new file mode 100644 index 00000000000..bb8148a2b38 Binary files /dev/null and b/src/doc/common/_vendor/python.inv differ diff --git a/src/doc/common/_vendor/rpy2.inv b/src/doc/common/_vendor/rpy2.inv new file mode 100644 index 00000000000..8220930b973 Binary files /dev/null and b/src/doc/common/_vendor/rpy2.inv differ diff --git a/src/doc/common/_vendor/scipy.inv b/src/doc/common/_vendor/scipy.inv new file mode 100644 index 00000000000..36244b07058 Binary files /dev/null and b/src/doc/common/_vendor/scipy.inv differ diff --git a/src/doc/common/_vendor/sympy.inv b/src/doc/common/_vendor/sympy.inv new file mode 100644 index 00000000000..e77acdcb095 Binary files /dev/null and b/src/doc/common/_vendor/sympy.inv differ diff --git a/src/doc/common/python3.inv b/src/doc/common/python3.inv deleted file mode 100644 index 50c7f1fa814..00000000000 Binary files a/src/doc/common/python3.inv and /dev/null differ diff --git a/src/doc/common/update-python-inv.sh b/src/doc/common/update-python-inv.sh deleted file mode 100755 index e6dcc843ced..00000000000 --- a/src/doc/common/update-python-inv.sh +++ /dev/null @@ -1,21 +0,0 @@ -#!/usr/bin/env bash -# The file python3.inv contains the database of Sphinx hyperlink targets used by -# the intersphinx extension. See -# -# http://sphinx-doc.org/ext/intersphinx.html -# -# To be able to compile Sage without accessing the net, we use a local copy of -# this database. Here is how to update it by downloading the file -# for the latest stable Python version: - -if command -v wget > /dev/null 2>&1 ; then - rm -f python.inv python2.inv python3.inv - wget https://docs.python.org/3/objects.inv -O - > python3.inv -elif command -v curl > /dev/null 2>&1 ; then - # On OS X, curl is installed by default, but not wget. - rm -f python.inv python2.inv python3.inv - curl https://docs.python.org/3/objects.inv > python3.inv -else - echo "Error: neither wget nor curl is installed." - return 1 -fi diff --git a/src/doc/en/developer/sage_manuals.rst b/src/doc/en/developer/sage_manuals.rst index 578419384c7..e57a4e13996 100644 --- a/src/doc/en/developer/sage_manuals.rst +++ b/src/doc/en/developer/sage_manuals.rst @@ -38,7 +38,7 @@ Sage's manuals are written in `ReST `_ ``SAGE_ROOT/src/doc/en``. - Some documents have been **translated** into other languages. In order to - access them, change en/ into fr/,es/, de/... See :ref:`section-manuals-names`. + access them, change ``en/`` into ``fr/``, ``es/``, ``de/``... See :ref:`section-manuals-names`. .. _section-manuals-edit: @@ -82,9 +82,12 @@ The documentation can contain links toward modules, classes, or methods, e.g.:: :mod:`link to a module ` :mod:`sage.module_name` (here the link's text is the module's name) -For links toward classes, methods, or function, replace **:mod:** by -**:class:**, **:meth:** or **:func:** respectively. See `Sphinx' documentation -`_. +For links toward classes, methods, or functions, replace ``:mod:`` by +``:class:``, ``:meth:``, or ``:func:``, respectively. See Sphinx' documentation +on `cross-referencing Python objects +`_ +and for the general syntax of +`roles `_. **Short links:** the link ``:func:`~sage.mod1.mod2.mod3.func1``` is equivalent to ``:func:`func1 ```: the function's name will be @@ -94,6 +97,72 @@ used as the link name, instead of its full path. absolute. If you are documenting ``method_one``, you can write ``:meth:`method_two```. +**Intersphinx references:** in the same way, you can refer to the modules, classes, +methods, functions of the Python standard library and of several Python packages +used by SageMath; see the `Intersphinx documentation +`_ +for details. Likewise, you can refer to the C functions of the +:ref:`FLINT ` library; see `Sphinx' documentation on +cross-referencing C constructs +`_ +for more information. + +.. LIST-TABLE:: + :widths: 4 7 5 + :header-rows: 0 + + * - Python + - ``:exc:`ValueError``` + - :exc:`ValueError` + * - :ref:`CVXOPT ` + - ``:func:`cvxopt.solvers.socp``` + - :func:`cvxopt.solvers.socp` + * - :ref:`CVXpy ` + - ``:class:`~cvxpy.atoms.log_det.log_det``` + - :class:`~cvxpy.atoms.log_det.log_det` + * - :ref:`cypari2 ` + - ``:class:`cypari2.gen.Gen``` + - :class:`cypari2.gen.Gen` + * - :ref:`cysignals ` + - ``:envvar:`CYSIGNALS_CRASH_DAYS``` + - :envvar:`CYSIGNALS_CRASH_DAYS` + * - :ref:`FLINT ` + - ``:c:func:`arith_bell_number``` + - :c:func:`arith_bell_number` + * - :ref:`gmpy2 ` + - ``:func:`gmpy2.gamma_inc``` + - :func:`gmpy2.gamma_inc` + * - :ref:`ipywidgets ` + - ``:mod:`~ipywidgets.widgets.widget_date``` + - :mod:`~ipywidgets.widgets.widget_date` + * - :ref:`Matplotlib ` + - ``:mod:`matplotlib.bezier``` + - :mod:`matplotlib.bezier` + * - :ref:`mpmath ` + - ``:attr:`mpmath.mp.khinchin``` + - :attr:`mpmath.mp.khinchin` + * - :ref:`NetworkX ` + - ``:attr:`~networkx.DiGraph.out_degree``` + - :attr:`~networkx.DiGraph.out_degree` + * - :ref:`NumPy ` + - ``:data:`numpy.NAN``` + - :data:`numpy.NAN` + * - :ref:`pplpy ` + - ``:mod:`ppl.polyhedron``` + - :mod:`ppl.polyhedron` + * - :ref:`rpy2 ` + - ``:class:`~rpy2.robjects.vectors.DataFrame``` + - :class:`~rpy2.robjects.vectors.DataFrame` + * - :ref:`SciPy ` + - ``:data:`scipy.special.huber``` + - :data:`scipy.special.huber` + * - :ref:`SymPy ` + - ``:class:`~sympy.diffgeom.WedgeProduct``` + - :class:`~sympy.diffgeom.WedgeProduct` + +To see the available cross references in any of these libraries, you can use the command +``./sage -python -m sphinx.ext.intersphinx src/doc/common/_vendor/numpy.inv``. + **Global namespace:** if an object (e.g. ``integral``) is automatically imported by Sage, you can link toward it without specifying its full path: diff --git a/src/doc/en/reference/matrices/index.rst b/src/doc/en/reference/matrices/index.rst index 89453635472..889a33bd717 100644 --- a/src/doc/en/reference/matrices/index.rst +++ b/src/doc/en/reference/matrices/index.rst @@ -29,7 +29,7 @@ following additional ways to compute with matrices: - The GSL C-library is included with Sage, and can be used via Cython. -- The ``scipy`` module provides support for +- The :mod:`scipy:scipy` module provides support for *sparse* numerical linear algebra, among many other things. - The ``numpy`` module, which you load by typing diff --git a/src/sage/calculus/desolvers.py b/src/sage/calculus/desolvers.py index 1a4692f3499..afeee69ce89 100644 --- a/src/sage/calculus/desolvers.py +++ b/src/sage/calculus/desolvers.py @@ -27,8 +27,8 @@ order equations, return list of points. - :func:`desolve_odeint` - Solve numerically a system of first-order ordinary - differential equations using ``odeint`` from `scipy.integrate module. - `_ + differential equations using :func:`~scipy:scipy.integrate.odeint` from + the module :mod:`scipy:scipy.integrate`. - :func:`desolve_system` - Solve a system of 1st order ODEs of any size using Maxima. Initial conditions are optional. @@ -1499,7 +1499,7 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=() mxstep=0, mxhnil=0, mxordn=12, mxords=5, printmessg=0): r""" Solve numerically a system of first-order ordinary differential equations - using ``odeint`` from scipy.integrate module. + using :func:`scipy:scipy.integrate.odeint`. INPUT: @@ -1517,8 +1517,9 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=() - ``compute_jac`` -- boolean. If True, the Jacobian of ``des`` is computed and used during the integration of stiff systems. Default value is False. - Other Parameters (taken from the documentation of odeint function from `scipy.integrate module. - `_) + Other Parameters (taken from the documentation of the + :func:`~scipy:scipy.integrate.odeint` function from + :mod:`scipy:scipy.integrate`): - ``rtol``, ``atol`` : float The input parameters ``rtol`` and ``atol`` determine the error diff --git a/src/sage/graphs/generators/families.py b/src/sage/graphs/generators/families.py index f090296938e..0d039d8db05 100644 --- a/src/sage/graphs/generators/families.py +++ b/src/sage/graphs/generators/families.py @@ -513,12 +513,13 @@ def BalancedTree(r, h): OUTPUT: The perfectly balanced tree of height `h \geq 1` and whose root has - degree `r \geq 2`. A ``NetworkXError`` is returned if `r < 2` or - `h < 1`. + degree `r \geq 2`. A :exc:`~networkx.exception.NetworkXError` is raised + if `r < 2` or `h < 1`. ALGORITHM: - Uses `NetworkX `_. + Uses the :ref:`NetworkX ` function + :func:`~networkx.generators.classic.balanced_tree`. EXAMPLES: diff --git a/src/sage/graphs/generic_graph.py b/src/sage/graphs/generic_graph.py index 7c942b4f5df..4d147efcd2f 100644 --- a/src/sage/graphs/generic_graph.py +++ b/src/sage/graphs/generic_graph.py @@ -1336,9 +1336,9 @@ def export_to_file(self, filename, format=None, **kwds): - ``format`` -- string (default: ``None``); select the output format explicitly. If set to ``None`` (default), the format is set to be the - file extension of ``filename``. Admissible formats are: ``adjlist``, - ``dot``, ``edgelist``, ``gexf``, ``gml``, ``graphml``, - ``multiline_adjlist``, ``pajek``, ``yaml``. + file extension of ``filename``. Admissible formats are: ``'adjlist'``, + ``'dot'``, ``'edgelist'``, ``'gexf'``, ``'gml'``, ``'graphml'``, + ``'multiline_adjlist'``, ``'pajek'``. - All other arguments are forwarded to the subfunction. For more information, see their respective documentation: @@ -1348,15 +1348,14 @@ def export_to_file(self, filename, format=None, **kwds): :widths: 30, 70 :delim: | - ``adjlist`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.adjlist.write_adjlist.html - ``dot`` | https://networkx.github.io/documentation/latest/reference/generated/networkx.drawing.nx_pydot.write_dot.html - ``edgelist`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.edgelist.write_edgelist.html - ``gexf`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.gexf.write_gexf.html - ``gml`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.gml.write_gml.html - ``graphml`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.graphml.write_graphml.html - ``multiline_adjlist`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.multiline_adjlist.write_multiline_adjlist.html - ``pajek`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.pajek.write_pajek.html - ``yaml`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.nx_yaml.write_yaml.html + ``'adjlist'`` | :func:`networkx.readwrite.adjlist.write_adjlist` + ``'dot'`` | :func:`networkx.drawing.nx_pydot.write_dot` + ``'edgelist'`` | :func:`networkx.readwrite.edgelist.write_edgelist` + ``'gexf'`` | :func:`networkx.readwrite.gexf.write_gexf` + ``'gml'`` | :func:`networkx.readwrite.gml.write_gml` + ``'graphml'`` | :func:`networkx.readwrite.graphml.write_graphml` + ``'multiline_adjlist'`` | :func:`networkx.readwrite.multiline_adjlist.write_multiline_adjlist` + ``'pajek'`` | :func:`networkx.readwrite.pajek.write_pajek` .. SEEALSO:: @@ -1366,7 +1365,7 @@ def export_to_file(self, filename, format=None, **kwds): .. NOTE:: This functions uses the ``write_*`` functions defined in NetworkX - (see http://networkx.lanl.gov/reference/readwrite.html). + (see :mod:`networkx.readwrite`). EXAMPLES:: diff --git a/src/sage/libs/flint/arith_sage.pyx b/src/sage/libs/flint/arith_sage.pyx index dcd22bbdf9a..302a3760a98 100644 --- a/src/sage/libs/flint/arith_sage.pyx +++ b/src/sage/libs/flint/arith_sage.pyx @@ -31,6 +31,10 @@ def bell_number(unsigned long n): See :wikipedia:`Bell_number`. + ALGORITHM: + + Uses :c:func:`arith_bell_number`. + EXAMPLES:: sage: from sage.libs.flint.arith_sage import bell_number diff --git a/src/sage/manifolds/differentiable/integrated_curve.py b/src/sage/manifolds/differentiable/integrated_curve.py index b0dd12bc744..063611becce 100644 --- a/src/sage/manifolds/differentiable/integrated_curve.py +++ b/src/sage/manifolds/differentiable/integrated_curve.py @@ -949,7 +949,7 @@ def solve(self, step=None, method='odeint', solution_key=None, use for the integration of the curve; available algorithms are: * ``'odeint'`` - makes use of - `scipy.integrate.odeint `_ + :func:`scipy:scipy.integrate.odeint` via Sage solver :func:`~sage.calculus.desolvers.desolve_odeint`; ``odeint`` invokes the LSODA algorithm of the @@ -961,9 +961,9 @@ def solve(self, step=None, method='odeint', solution_key=None, makes use of Maxima's dynamics package via Sage solver :func:`~sage.calculus.desolvers.desolve_system_rk4` (quite slow) * ``'dopri5'`` - Dormand-Prince Runge-Kutta of order (4)5 provided by - `scipy.integrate.ode `_ + :obj:`scipy:scipy.integrate.ode` * ``'dop853'`` - Dormand-Prince Runge-Kutta of order 8(5,3) provided by - `scipy.integrate.ode `_ + :obj:`scipy:scipy.integrate.ode` and those provided by ``GSL`` via Sage class :class:`~sage.calculus.ode.ode_solver`: @@ -1425,8 +1425,8 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None, Integrate the curve numerically over the domain of integration, with the ability to switch chart mid-integration. - The only supported solver is - `scipy.integrate.ode `_, because it supports basic event handling, needed to detect when the + The only supported solver is :obj:`scipy:scipy.integrate.ode`, + because it supports basic event handling, needed to detect when the curve is reaching the frontier of the chart. This is an adaptive step solver. So the ``step`` is not the step of integration but instead the step used to peak at the current chart, and switch if needed. @@ -1525,8 +1525,8 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None, The integration is done as usual, but using the method :meth:`solve_across_charts` instead of :meth:`solve`. This forces the - use of ``scipy.integrate.ode`` as the solver, because of event handling - support. + use of :obj:`scipy:scipy.integrate.ode` as the solver, because of event + handling support. The argument ``verbose=True`` will cause the solver to write a small message each time it is switching chart:: diff --git a/src/sage/matrix/matrix_double_dense.pyx b/src/sage/matrix/matrix_double_dense.pyx index ede06f07f7f..6877a924de2 100644 --- a/src/sage/matrix/matrix_double_dense.pyx +++ b/src/sage/matrix/matrix_double_dense.pyx @@ -594,8 +594,8 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): ALGORITHM: - Computation is performed by the ``norm()`` function of - the SciPy/NumPy library. + Computation is performed by the :func:`~scipy:scipy.linalg.norm` + function of the SciPy/NumPy library. EXAMPLES: @@ -739,7 +739,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): ALGORITHM: The singular values come from the SVD decomposition - computed by SciPy/NumPy. + computed by SciPy/NumPy using :func:`scipy:scipy.linalg.svd`. EXAMPLES: @@ -1073,7 +1073,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): - ``'default'`` - applicable to any matrix with double-precision floating point entries. - Uses the :meth:`~scipy.linalg.eigvals` method from SciPy. + Uses the :func:`~scipy:scipy.linalg.eigvals` function from SciPy. - ``'symmetric'`` - converts the matrix into a real matrix (i.e. with entries from :class:`~sage.rings.real_double.RDF`), @@ -1081,9 +1081,9 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): algorithm can be significantly faster than the ``'default'`` algorithm. - - ``'hermitian'`` - uses the :meth:`~scipy.linalg.eigh` method - from SciPy, which applies only to real symmetric or complex - Hermitian matrices. Since Hermitian is defined as a matrix + - ``'hermitian'`` - uses the :func:`~scipy:scipy.linalg.eigh` + function from SciPy, which applies only to real symmetric or + complex Hermitian matrices. Since Hermitian is defined as a matrix equaling its conjugate-transpose, for a matrix with real entries this property is equivalent to being symmetric. This algorithm can be significantly faster than the @@ -1707,6 +1707,10 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): Find a solution `X` to the equation `A X = B` if ``self`` is a square matrix `A`. + ALGORITHM: + + Uses the function :func:`scipy:scipy.linalg.solve` from SciPy. + TESTS:: sage: # needs sage.symbolic @@ -1730,6 +1734,10 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): Compute a least-squares solution `X` to the equation `A X = B` where ``self`` is the matrix `A`. + ALGORITHM: + + Uses the function :func:`scipy:scipy.linalg.lstsq` from SciPy. + TESTS:: sage: A = matrix(RDF, 3, 2, [1, 3, 4, 2, 0, -3]) @@ -1754,7 +1762,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): ALGORITHM: - Use numpy + Uses :func:`scipy:scipy.linalg.det`. EXAMPLES:: @@ -2037,7 +2045,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): ALGORITHM: - Calls "linalg.qr" from SciPy, which is in turn an + Calls :func:`scipy:scipy.linalg.qr` from SciPy, which is in turn an interface to LAPACK routines. EXAMPLES: diff --git a/src/sage/matroids/matroids_plot_helpers.py b/src/sage/matroids/matroids_plot_helpers.py index 3c084931cce..b7a3d7d6d03 100644 --- a/src/sage/matroids/matroids_plot_helpers.py +++ b/src/sage/matroids/matroids_plot_helpers.py @@ -20,8 +20,9 @@ via an optimization that gives aesthetically pleasing point placement (in some sense. This is not yet implemented). One can then use ``createline`` function to produce sequence of ``100`` points on a smooth - curve containing the points in the specified line which inturn uses - ``scipy.interpolate.splprep`` and ``scipy.interpolate.splev``. Then one + curve containing the points in the specified line which in turn uses + :func:`scipy:scipy.interpolate.splprep` and + :func:`scipy:scipy.interpolate.splev`. Then one can use sage's graphics primitives ``line``, ``point``, ``text`` and ``points`` to produce graphics object containing points (ground set elements) and lines (for a rank 3 matroid, these are flats of rank 2 of diff --git a/src/sage/modules/vector_double_dense.pyx b/src/sage/modules/vector_double_dense.pyx index 74c73270ffc..1d5f6e8c4ab 100644 --- a/src/sage/modules/vector_double_dense.pyx +++ b/src/sage/modules/vector_double_dense.pyx @@ -395,8 +395,8 @@ cdef class Vector_double_dense(Vector_numpy_dense): ALGORITHM: - Computation is performed by the ``norm()`` function of - the SciPy/NumPy library. + Computation is performed by the :func:`~scipy:scipy.linalg.norm` + function of the SciPy/NumPy library. EXAMPLES: diff --git a/src/sage/numerical/optimize.py b/src/sage/numerical/optimize.py index 35c316e905d..54262183b1b 100644 --- a/src/sage/numerical/optimize.py +++ b/src/sage/numerical/optimize.py @@ -33,8 +33,8 @@ def find_root(f, a, b, xtol=10e-13, rtol=2.0**-50, maxiter=100, full_output=Fals to lie within ``xtol`` of the value return. Should be `\geq 0`. The routine modifies this to take into account the relative precision of doubles. By default, rtol is ``4*numpy.finfo(float).eps``, the - minimum allowed value for ``scipy.optimize.brentq``, which is what - this method uses underneath. This value is equal to ``2.0**-50`` for + minimum allowed value for :func:`scipy:scipy.optimize.brentq`, which is + what this method uses underneath. This value is equal to ``2.0**-50`` for IEEE-754 double precision floats as used by Python. - ``maxiter`` -- integer; if convergence is not achieved in @@ -274,9 +274,7 @@ def find_local_minimum(f, a, b, tol=1.48e-08, maxfun=500): ALGORITHM: - Uses `scipy.optimize.fminbound - `_ - which uses Brent's method. + Uses :func:`scipy:scipy.optimize.fminbound` which uses Brent's method. AUTHOR: @@ -338,8 +336,8 @@ def minimize(func, x0, gradient=None, hessian=None, algorithm="default", .. NOTE:: For additional information on the algorithms implemented in this function, - consult SciPy's `documentation on optimization and root - finding `_ + consult SciPy's :mod:`documentation on optimization and root + finding `. EXAMPLES: @@ -650,8 +648,8 @@ def find_fit(data, model, initial_guess=None, parameters=None, variables=None, s ALGORITHM: - Uses ``scipy.optimize.leastsq`` which in turn uses MINPACK's lmdif and - lmder algorithms. + Uses :func:`scipy:scipy.optimize.leastsq` which in turn uses MINPACK's + ``lmdif`` and ``lmder`` algorithms. """ import numpy diff --git a/src/sage/stats/basic_stats.py b/src/sage/stats/basic_stats.py index 96684023b71..83dc50b4e89 100644 --- a/src/sage/stats/basic_stats.py +++ b/src/sage/stats/basic_stats.py @@ -108,7 +108,7 @@ def mode(v): in `v`, then the mode is the list of elements of `v` that occur `n` times. The list is sorted if possible. - This function is deprecated. Use :func:`scipy.stats.mode` or + This function is deprecated. Use :func:`scipy:scipy.stats.mode` or :func:`statistics.mode` instead. .. NOTE:: diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index c5329e79cfd..9bd98aee7d0 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -258,30 +258,85 @@ def sphinx_plot(graphics, **kwds): # include the todos todo_include_todos = True -# Cross-links to other project's online documentation. -python_version = sys.version_info.major +# +# intersphinx: Cross-links to other projects' online or installed documentation. +# +SAGE_DOC_REMOTE_INVENTORIES = os.environ.get('SAGE_DOC_REMOTE_INVENTORIES', 'no') == 'yes' + +_vendored_inventories_dir = os.path.join(SAGE_DOC_SRC, "common", "_vendor") + + +# Run "sage -python -m sage_docbuild.vendor" to update src/doc/common/_vendor/*.inv +_intersphinx_targets = { + 'cvxopt': ['https://cvxopt.org/userguide/'], + 'cvxpy': ['https://www.cvxpy.org/'], + 'cypari2': ['https://cypari2.readthedocs.io/en/latest/'], + 'cysignals': ['https://cysignals.readthedocs.io/en/latest/'], + 'flint': ['https://flintlib.org/doc/'], + 'fpylll': ['https://fpylll.readthedocs.io/en/latest/'], + 'gmpy2': ['https://gmpy2.readthedocs.io/en/latest/'], + 'ipywidgets': ['https://ipywidgets.readthedocs.io/en/stable/'], + 'matplotlib': ['https://matplotlib.org/stable/'], + 'mpmath': ['https://mpmath.org/doc/current/'], + 'networkx': ['https://networkx.org/documentation/stable/'], + 'numpy': ['https://numpy.org/doc/stable/'], + 'pplpy': [PPLPY_DOCS, 'https://www.sagemath.org/pplpy/'], + 'python': ['https://docs.python.org/'], + 'rpy2': ['https://rpy2.github.io/doc/latest/html/'], + 'scipy': ['https://docs.scipy.org/doc/scipy/'], + 'sympy': ['https://docs.sympy.org/latest/'], +} + + +def _intersphinx_mapping(key): + inventories = [] + link_target = None + for target in _intersphinx_targets[key]: + if not target: + pass + elif target.startswith('http'): + if not link_target: + link_target = target + if SAGE_DOC_REMOTE_INVENTORIES: + inventories.append(None) # Try downloading inventory from link_target + elif os.path.exists(target): + if not link_target: + link_target = target + inventory = os.path.join(target, 'objects.inv') + if os.path.exists(inventory): + inventories.append(inventory) + break + else: + vendored_inventory = os.path.join(_vendored_inventories_dir, key + '.inv') + if os.path.exists(vendored_inventory): + inventories.append(vendored_inventory) + else: + # To avoid docbuild failures when building Sage without internet + # connection, we use the local python inventory file as a fallback for other + # projects. Cross-references will not be resolved in that case, but the + # docbuild will still succeed. + python_inventory_file = os.path.join(_vendored_inventories_dir, "python.inv") + inventories.append(python_inventory_file) + assert link_target + if len(inventories) == 1: + return link_target, inventories[0] + return link_target, tuple(inventories) def set_intersphinx_mappings(app, config): """ Add precompiled inventory (the objects.inv) """ + app.config.intersphinx_mapping = {} + refpath = os.path.join(SAGE_DOC, "html", "en", "reference") invpath = os.path.join(SAGE_DOC, "inventory", "en", "reference") if app.config.multidoc_first_pass == 1 or \ not (os.path.exists(refpath) and os.path.exists(invpath)): - app.config.intersphinx_mapping = {} return - app.config.intersphinx_mapping = { - 'python': ('https://docs.python.org/', - os.path.join(SAGE_DOC_SRC, "common", - "python{}.inv".format(python_version))), - } - if PPLPY_DOCS and os.path.exists(os.path.join(PPLPY_DOCS, 'objects.inv')): - app.config.intersphinx_mapping['pplpy'] = (PPLPY_DOCS, None) - else: - app.config.intersphinx_mapping['pplpy'] = ('https://www.labri.fr/perso/vdelecro/pplpy/latest/', None) + app.config.intersphinx_mapping = {key: _intersphinx_mapping(key) + for key in _intersphinx_targets} # Add master intersphinx mapping dst = os.path.join(invpath, 'objects.inv') diff --git a/src/sage_docbuild/vendor.py b/src/sage_docbuild/vendor.py new file mode 100644 index 00000000000..5009f6e35de --- /dev/null +++ b/src/sage_docbuild/vendor.py @@ -0,0 +1,32 @@ +# "sage -python -m sage_docbuild.vendor" updates src/doc/common/_vendor/*.inv +# +import os +import sys + +import requests + +from .conf import _vendored_inventories_dir, _intersphinx_targets + + +if __name__ == '__main__': + if not _vendored_inventories_dir: + print('Error: sage_docbuild.vendor needs to be able to write to SAGE_SRC', file=sys.stderr) + sys.exit(1) + errors = 0 + for key, targets in _intersphinx_targets.items(): + for target in targets: + if target.startswith('http'): + inv_url = target + 'objects.inv' + fname = os.path.join(_vendored_inventories_dir, key + '.inv') + print(f'Requesting {inv_url}', flush=True) + try: + r = requests.get(inv_url) + with open(fname, 'wb') as fd: + fd.write(r.content) + except Exception as e: + print(f'Error: {e}') + errors += 1 + else: + print(f'Updated {fname}') + break + sys.exit(errors)