Intersphinx link to lu_solve

[bertiewooster]

I am writing a guide page on solving a matrix equation (set of linear equations) for SymPy, which is built on mpmath. I would like to include an intersphinx link to mpmath's lu_solve so that SymPy's documentation will be robust against changes to mpmath's documentation. I would appreciate your help in creating an intersphinx link.

1. First, is there an API documentation link in the mpmath docs for lu_solve? My search for "lu_solve" found the matrices page, whose Linear equations section discusses lu_solve. But I didn't find an API documentation link for lu_solve.
   • If there is no such API documentation, my fallback option will be to link to https://mpmath.org/doc/current/matrices.html#linear-equations, which could break if the mpmath documentation structure is changed.
2. If yes, what is the code path to lu_solve, which I believe is a method (rather than a function)? For example, I can create an intersphinx link to isinf using mpmath.isinf. For lu_solve, I tried all of the following without success:
   • mpmath.matrices.linalg.LinearAlgebraMethods.lu_solve
   • mpmath.LinearAlgebraMethods.lu_solve
   • mpmath.lu_solve

[bertiewooster]

@skirpichev Thank you for exposing mpmath.lu_solve docstring in the sphinx docs. I am not yet able to link to it from the SymPy documentation using intersphinx via MyST markdown

{external:func}`mpmath.lu_solve`

whereas I am able to link to another mpmath function mnorm using anologous markdown:

{external:func}`mpmath.mnorm`

Are the mpmath docs not updated until the next mpmath release? If so, that would seem to explain why I cannot yet link to mpmath.lu_solve.

[skirpichev]

If so, that would seem to explain why I cannot yet link to mpmath.lu_solve.

You are right, the mpmath.org/doc/current/ docs aren't up to date. But you could use (for tests!) docs on the readthedocs.org, it's updated: https://mpmath.readthedocs.io/en/latest/matrices.html#mpmath.lu_solve Let me know if you still have problems.

[skirpichev]

@fredrik-johansson, could you please update https://mpmath.org/doc/current/ or, alternatively, use https://mpmath.readthedocs.io/ for the project documentation? The RTFD mpmath project has the stable version (1.3.0) & the latest docs from git tree. With RTFD we also can automatically update docs for the master's version and build docs for PR's. Unfortunately, this will require your assistance to enable the github integration :( I can also add you as a co-maintainer for this RTFD project, if you wish.

[bertiewooster]

@skirpichev Thanks! I tried to change the Intersphinx reference to mpmath to https://mpmath.readthedocs.io/en/latest/ but got a fatal error

Extension error (sphinx.ext.intersphinx):
Handler <function load_mappings at 0xffff97976ca0> for event 'builder-inited' threw an exception (exception: '<' not supported between instances of 'dict' and 'dict')
make[1]: *** [Makefile:69: _html] Error 2

so I didn't pursue referring to the Read The Docs site.

I did create a SymPy draft pull request which currently fails and should succeed once the mpmath docs are updated at https://mpmath.org/doc/current/.

[skirpichev]

I tried to change the Intersphinx reference to mpmath to https://mpmath.readthedocs.io/en/latest/ but got a fatal error

Probably, you did some typo in the intersphinx_mapping. Here is a working diff, which I've tested on the gmpy2 docs:

diff --git a/docs/conf.py b/docs/conf.py
index 06790e9..195c289 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -30,7 +30,8 @@ autodoc_default_options = {'members': True}

 # Contains mapping the locations and names of other projects that
 # should be linked to in this documentation.
-intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
+intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
+                       'mpmath': ('https://mpmath.readthedocs.io/en/latest/', None),}

 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

[bertiewooster]

Hmm, that's what I tried:

# Enable links to other packages
intersphinx_mapping = {
    "matplotlib": ("https://matplotlib.org/stable/", None),
    "mpmath": ("https://mpmath.readthedocs.io/en/latest/", None),
    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
}

Seems like https://mpmath.org/doc/current/ is the canonical version anyway, so I'll wait for that to be updated.

[skirpichev]

Ok, I tried also this patch on top of your pr:

$ gh pr checkout 25167
$ git diff
diff --git a/doc/src/conf.py b/doc/src/conf.py
index 28dd48c517..cf41fd8bed 100644
--- a/doc/src/conf.py
+++ b/doc/src/conf.py
@@ -403,7 +403,7 @@
 # Enable links to other packages
 intersphinx_mapping = {
     'matplotlib': ('https://matplotlib.org/stable/', None),
-    'mpmath': ('https://mpmath.org/doc/current/', None),
+    'mpmath': ('https://mpmath.readthedocs.io/en/latest/', None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
 }
$ sudo apt install imagemagick graphviz librsvg2-bin
...
$ cd doc
$ pip install -r requirements.txt
...
$ make html
make -s _html || make -s printwarnings
Running Sphinx v6.1.3
myst v1.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'dollarmath', 'linkify', 'tasklist'}, disable_syntax=[], all_links_extern
al=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anc
hors=6, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=False, dmath_allow_labels=T
rue, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|out
put_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
loading intersphinx inventory from https://matplotlib.org/stable/objects.inv...
loading intersphinx inventory from https://mpmath.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/scipy/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 293 source files that are out of date
updating environment: [new config] 293 added, 0 changed, 0 removed
/home/sk/src/sympy/sympy/plotting/plot.py:1808: RuntimeWarning: invalid value encountered in scalar divide
  cos_theta = dot_product / (vector_a_norm * vector_b_norm)
/home/sk/src/sympy/sympy/plotting/plot.py:1808: RuntimeWarning: invalid value encountered in scalar divide
  cos_theta = dot_product / (vector_a_norm * vector_b_norm)
/usr/local/lib/python3.11/importlib/__init__.py:126: SymPyDeprecationWarning:

The sympy.testing.randtest submodule is deprecated. Use sympy.core.random instead.

See https://docs.sympy.org/latest/explanation/active-deprecations.html#deprecated-sympy-testing-randtest
for details.

This has been deprecated since SymPy version 1.10. It
will be removed in a future version of SymPy.

  return _bootstrap._gcd_import(name[level:], package, level)
reading sources... [100%] tutorials/intro-tutorial/solvers
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
a0writing output... [ 31%] modules/integrals/g-functions                                                                                                       writing output... [100%] tutorials/intro-tutorial/solvers
generating indices... genindex py-modindex done
Creating redirect 'guides/getting_started/install.html' to '../../install.html'.
Creating redirect 'documentation-style-guide.html' to 'contributing/documentation-style-guide.html'.
Creating redirect 'gotchas.html' to 'explanation/gotchas.html'.
Creating redirect 'special_topics/classification.html' to '../explanation/classification.html'.
Creating redirect 'special_topics/finite_diff_derivatives.html' to '../explanation/finite_diff_derivatives.html'.
Creating redirect 'special_topics/intro.html' to '../explanation/index.html'.
Creating redirect 'special_topics/index.html' to '../explanation/index.html'.
Creating redirect 'modules/index.html' to '../reference/index.html'.
Creating redirect 'modules/physics/index.html' to '../../reference/public/physics/index.html'.
Creating redirect 'guides/contributing/index.html' to '../../contributing/index.html'.
Creating redirect 'guides/contributing/dev-setup.html' to '../../contributing/dev-setup.html'.
Creating redirect 'guides/contributing/dependencies.html' to '../../contributing/dependencies.html'.
Creating redirect 'guides/contributing/build-docs.html' to '../../contributing/new-contributors-guide/build-docs.html'.
Creating redirect 'guides/contributing/debug.html' to '../../contributing/debug.html'.
Creating redirect 'guides/contributing/docstring.html' to '../../contributing/docstring.html'.
Creating redirect 'guides/documentation-style-guide.html' to '../../contributing/contributing/documentation-style-guide.html'.
Creating redirect 'guides/make-a-contribution.html' to '../../contributing/make-a-contribution.html'.
Creating redirect 'guides/contributing/deprecations.html' to '../../contributing/deprecations.html'.
Creating redirect 'tutorial/preliminaries.html' to '../tutorials/intro-tutorial/preliminaries.html'.
Creating redirect 'tutorial/intro.html' to '../tutorials/intro-tutorial/intro.html'.
Creating redirect 'tutorial/index.html' to '../tutorials/intro-tutorial/index.html'.
Creating redirect 'tutorial/gotchas.html' to '../tutorials/intro-tutorial/gotchas.html'.
Creating redirect 'tutorial/features.html' to '../tutorials/intro-tutorial/features.html'.
Creating redirect 'tutorial/next.html' to '../tutorials/intro-tutorial/next.html'.
Creating redirect 'tutorial/basic_operations.html' to '../tutorials/intro-tutorial/basic_operations.html'.
Creating redirect 'tutorial/printing.html' to '../tutorials/intro-tutorial/printing.html'.
Creating redirect 'tutorial/simplification.html' to '../tutorials/intro-tutorial/simplification.html'.
Creating redirect 'tutorial/calculus.html' to '../tutorials/intro-tutorial/calculus.html'.
Creating redirect 'tutorial/solvers.html' to '../tutorials/intro-tutorial/solvers.html'.
Creating redirect 'tutorial/matrices.html' to '../tutorials/intro-tutorial/matrices.html'.
Creating redirect 'tutorial/manipulation.html' to '../tutorials/intro-tutorial/manipulation.html'.
writing additional pages... search done
copying images... [100%] pics/consoleascii.png
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.  

I see no problems locally and I can't guess what's wrong with your local setup. Could you try this patch in your pr?

[skirpichev]

FYI, @bertiewooster, you can see docs preview in CircleCI job of the SymPy here: https://app.circleci.com/pipelines/github/sympy/sympy/5209/workflows/b0097e4c-be36-4988-ae40-bc9e6728abdf/jobs/5132/artifacts

[bertiewooster]

@skirpichev Ah, thanks. There used to be a separate job that simply linked to the homepage of the docs preview. I now understand that you can get there by clicking doc/_build/html/index.html.

At any rate, the doc preview of the page that links to lu_solve has a valid link to mpmath's documentation page on readthedocs. So the Intersphinx setup works on the CI build, which is what matters rather than my local machine.

Is mpmath's readthedocs version OK to link to instead of https://mpmath.org/doc/current/? In other words, is the readthedocs version the canonical version, or at least consistently updated? If so, I'll mark my SymPy pull request as ready for review so it can be merged upon approval.

[skirpichev]

On Sat, Jun 03, 2023 at 08:42:34PM -0700, Jeremy Monat wrote:

Is mpmath's readthedocs version OK to link to instead of [5]https://mpmath.org/doc/current/? In other words, is the readthedocs version the canonical version, or at least consistently updated?

No, please don't do this. I'll open a thread on the mpmath mail list about this issue. So far, the mpmath RTFD project is not an official place for the project docs. (And it requires a manual intervention to trigger a build.)

[bertiewooster]

Understand. I won't mark the PR as ready for review. I will instead await notification that either

• the readthedocs version is an official place for the project docs (in which case I'd submit for review as is), or
• the docs on https://mpmath.org/doc/current/ have been updated to expose the lu_solve docstring (in which case I'd revert the last commit, check that the documentation builds correctly with linking to https://mpmath.org/doc/current/, and then submit for review).

[skirpichev]

You can track progress here: #709