using :doc: tag instead of relative links with ../ to html

[dimpase]

One can use :doc: tag here:

--- a/src/sage/rings/polynomial/msolve.py
+++ b/src/sage/rings/polynomial/msolve.py
@@ -8,7 +8,7 @@ based on Gröbner bases.
 This module provide implementations of some operations on polynomial ideals
 based on msolve.
 
-Note that the `optional package msolve <../../../../spkg/msolve.html>`_ must be installed.
+Note that the :doc:`optional package msolve <spkg/msolve>` must be installed.
 
 .. SEEALSO::
 

and it looks much more Sphinxic to me. I propose to do this for many other places where this is present - this would also make these links in pdf docs meaningful.

Originally posted by @dimpase in #36611 (comment)

[dimpase]

It's actually doesn't quite work, i.e. it needs two runs of make to succeed. On the 1st run one gets an error

[sagemath_doc_html-none] [polynomia] The inventory files are in ../../local/share/doc/sage/inventory/en/reference/polynomial_rings.
[sagemath_doc_html-none] Error building the documentation.
[sagemath_doc_html-none] Traceback (most recent call last):
[sagemath_doc_html-none]   File "<frozen runpy>", line 198, in _run_module_as_main
[sagemath_doc_html-none]   File "<frozen runpy>", line 88, in _run_code
[sagemath_doc_html-none]   File "/mnt/opt/Sage/sage-clang/pkgs/sage-docbuild/sage_docbuild/__main__.py", line 508, in <module>
[sagemath_doc_html-none]     sys.exit(main())
[sagemath_doc_html-none]              ^^^^^^
[sagemath_doc_html-none]   File "/mnt/opt/Sage/sage-clang/pkgs/sage-docbuild/sage_docbuild/__main__.py", line 504, in main
[sagemath_doc_html-none]     builder()
[sagemath_doc_html-none]   File "/mnt/opt/Sage/sage-clang/pkgs/sage-docbuild/sage_docbuild/builders.py", line 818, in _wrapper
[sagemath_doc_html-none]     getattr(DocBuilder, build_type)(self, *args, **kwds)
[sagemath_doc_html-none]   File "/mnt/opt/Sage/sage-clang/pkgs/sage-docbuild/sage_docbuild/builders.py", line 162, in f
[sagemath_doc_html-none]     runsphinx()
[sagemath_doc_html-none]   File "/mnt/opt/Sage/sage-clang/pkgs/sage-docbuild/sage_docbuild/sphinxbuild.py", line 327, in runsphinx
[sagemath_doc_html-none]     sys.stderr.raise_errors()
[sagemath_doc_html-none]   File "/mnt/opt/Sage/sage-clang/pkgs/sage-docbuild/sage_docbuild/sphinxbuild.py", line 263, in raise_errors
[sagemath_doc_html-none]     raise OSError(self._error)
[sagemath_doc_html-none] OSError: /mnt/opt/Sage/sage-clang/src/sage/rings/polynomial/msolve.py:docstring of sage.rings.polynomial.msolve:7: WARNING: unknown document: 'spkg/msolve'
[sagemath_doc_html-none] 

So it's a bit of chicken & egg issue here.

[mkoeppe]

Can't we just refer to this section by label (:ref:spkg_msolve`)?

[dimpase]

Can't we just refer to this section by label (:ref:spkg_msolve`)?

yes, this works. We have several ../../ other URLs in docstrings, which are probably not so easy to fix. I'll try adding tags, and corresponding :ref:, in places where rst files are in the git tree.

[dimpase]

OK, the following works. I'll do a PR based on this, to remove as many ../*.html in docstring URLs as possible.

--- a/src/doc/en/reference/asymptotic/index.rst
+++ b/src/doc/en/reference/asymptotic/index.rst
@@ -1,3 +1,5 @@
+.. _asymptotic:
+
 Asymptotic Expansions
 =====================
 
--- a/src/sage/rings/big_oh.py
+++ b/src/sage/rings/big_oh.py
@@ -3,7 +3,7 @@ Big O for various types (power series, p-adics, etc.)
 
 .. SEEALSO::
 
-    - `asymptotic expansions <../../../asymptotic/index.html>`_
+    - :ref:`asymptotic`
     - `p-adic numbers <../../../padics/index.html>`_
     - `power series <../../../power_series/index.html>`_
     - `polynomials <../../../polynomial_rings/index.html>`_
@@ -90,7 +90,7 @@ def O(*x, **kwds):
         sage: K(11^-12, 15)
         11^-12 + O(11^15)
 
-    We can also work with `asymptotic expansions`_::
+    We can also work with :ref:`asymptotic expansions <asymptotic>`::
 
         sage: A.<n> = AsymptoticRing(growth_group='QQ^n * n^QQ * log(n)^QQ',            # needs sage.symbolic
         ....:                        coefficient_ring=QQ); A
--- a/src/sage/rings/polynomial/msolve.py
+++ b/src/sage/rings/polynomial/msolve.py
@@ -8,7 +8,7 @@ based on Gröbner bases.
 This module provide implementations of some operations on polynomial ideals
 based on msolve.
 
-Note that the `optional package msolve <../../../../spkg/msolve.html>`_ must be installed.
+Note that the :ref:`spkg_msolve` must be installed.
 
 .. SEEALSO::
 

[mkoeppe]

I've put the changes using :ref:`spkg_msolve` on #37376.

[dimpase]

fixed by #37376