Opened 2 years ago

Last modified 4 weeks ago

#30475 new defect

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

Reported by: mkoeppe Owned by:
Priority: major Milestone: sage-9.9
Component: build Keywords:
Cc: jhpalmieri, gh-DaveWitteMorris Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

GitHub link to the corresponding issue

Description (last modified by 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

Change History (11)

comment:1 Changed 2 years ago by mkoeppe

Description: modified (diff)

comment:2 Changed 2 years ago by mkoeppe

Description: modified (diff)

comment:3 Changed 2 years ago by mkoeppe

Milestone: sage-9.2sage-9.3

comment:4 Changed 2 years ago by mkoeppe

Milestone: sage-9.3sage-9.4

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

comment:5 Changed 19 months ago by mkoeppe

Milestone: sage-9.4sage-9.5

comment:6 Changed 14 months ago by mkoeppe

Milestone: sage-9.5sage-9.6

comment:7 Changed 10 months ago by mkoeppe

Milestone: sage-9.6sage-9.7

comment:8 Changed 7 months ago by klee

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?

comment:9 Changed 7 months ago by mkoeppe

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

comment:10 Changed 5 months ago by mkoeppe

Milestone: sage-9.7sage-9.8

comment:11 Changed 4 weeks ago by mkoeppe

Milestone: sage-9.8sage-9.9
Note: See TracTickets for help on using tickets.