Currently, (1) at runtime sage requires some files from under SAGE_DOC_SRC. For example:

$ git grep SAGE_DOC_SRC -- src/sage
[..]
src/sage/misc/sagedoc.py:    sys.path = [os.path.join(SAGE_DOC_SRC, 'common')] + oldpath
[..]
src/sage/misc/sphinxify.py:    confdir = os.path.join(SAGE_DOC_SRC, 'en', 'introspect')

However, this is awkward for binary distros such as Debian, who don't install source code onto end user machines by default. Indeed, even Sage's own Makefiles don't install these files into SAGE_LOCAL, even though they are a runtime necessity.

In addition to this, (2) there are many cases where Sage tracks SAGE_DOC_SRC and hacks it into sys.path via os.environ, which is not very clean.

This ticket proposes the following change (or something similar)

• src/doc/common/* -> src/sage/docs/common/*
• src/doc/en/introspect/* -> src/sage/docs/introspect/*

This would solve the above two issues - instead of (2) one can just do from sage.doc.common import conf or from sage.doc.introspect import conf, and (1) is taken care of automatically because everything under src/sage is installed as standard python modules.

One could also remove the OMIT = ["introspect"] exception in src/sage_setup/docbuild/build_options.py.

Does this sound sensible? If so I can do this for our Debian packaging already, test it, and send in an initial patch.

Depends on #22611
Depends on #22655

CC: @hivert @isuruf @kiwifb @jhpalmieri @antonio-rojas

Component: documentation

Keywords: days85

Author: Erik Bray

Branch/Commit: u/embray/ticket-21732 @ 77b5428

Reviewer: François Bissey

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