sage -docbuild: error building docs of single file with relative imports

[mkoeppe]

Follow-up from #29651:

The approach of SingleFileBuilder, creating a symlink to the source file, is not compatible with from .module import.

Example:

$ ./sage -docbuild file=src/sage/geometry/polyhedron/base.py html 
[html     ] building [html]: targets for 1 source files that are out of date
[html     ] updating environment: [new config] 1 added, 0 changed, 0 removed
[html     ] WARNING: autodoc: failed to import module 'base'; the following exception was raised:
[html     ] attempted relative import with no known parent package
[html     ] writing additional pages...  searchdone
[html     ] copying static files... ... done
[html     ] dumping search index in English (code: en)... done
[html     ] The HTML pages are in ../../../../.sage/docbuild/base/output/html.
Error building the documentation.

Instead, we should infer the fully qualified module name from the file name (see for example #30452) and import this module.

See also:

• #6389 expose building documentation for user modules not in the Sage library

CC: @jhpalmieri @DaveWitteMorris

Component: build

Issue created by migration from https://trac.sagemath.org/ticket/30475

[mkoeppe]

Description changed:

--- 
+++ 
@@ -17,3 +17,5 @@
 Error building the documentation.
 ```
 
+Instead, we should infer the fully qualified module name from the file name (see for example #30452) and import this module.
+

[mkoeppe]

Description changed:

--- 
+++ 
@@ -19,3 +19,6 @@
 
 Instead, we should infer the fully qualified module name from the file name (see for example #30452) and import this module.
 
+
+See also:
+- #6389 expose building documentation for user modules not in the Sage library

[mkoeppe]

comment:4

Setting new milestone based on a cursory review of ticket status, priority, and last modification date.

[kwankyu]

comment:8

Sorry for a naive question. What is the primary use of the single file doc builder? I didn't have an occasion to use it myself.

If the file is in the sage library, isn't it enough to use sage -docbuild reference/discrete_geometry html for src/sage/geometry/polyhedron/base.py, for instance?

[mkoeppe]

comment:9

I think it can be useful for users who are working on a file outside of the Sage source tree