expose building documentation for user modules not in the Sage library

[malb]

It would be neat to be able to do:

sage -docbuild foo.py

for a single file not in the library.

See also:

• Build doc sage-numerical-backends-coin#2

CC: @mkoeppe @jdemeyer @vbraun @fchapoton @williamstein @dimpase @nthiery @hivert @embray

Component: documentation

Keywords: sphinx

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

[fchapoton]

comment:1

This used to work, but no longer

sage -docbuild file=my_own_code.py html

[jhpalmieri]

comment:3

The line

    assert app.outdir.startswith(SAGE_DOC)

in src/sage_setup/docbuild/ext/multidocs.py raises an error. I think we should disable this assertion when using the file=... argument to sage --docbuild.

[mkoeppe]

comment:5

Replying to @jhpalmieri:

The line

    assert app.outdir.startswith(SAGE_DOC)

in src/sage_setup/docbuild/ext/multidocs.py raises an error. I think we should disable this assertion when using the file=... argument to sage --docbuild.

This assert is in citation_dir.
How should single-file docbuilds handle citations?

[jhpalmieri]

comment:6

Replying to @mkoeppe:

Replying to @jhpalmieri:

The line

    assert app.outdir.startswith(SAGE_DOC)

in src/sage_setup/docbuild/ext/multidocs.py raises an error. I think we should disable this assertion when using the file=... argument to sage --docbuild.

This assert is in citation_dir.
How should single-file docbuilds handle citations?

Ignore them? Or at least ignore references to citations in the Sage library: I think it should treat the single file as being unconnected to the Sage library.

[mkoeppe]

comment:8

Cc'ing people who are currently working on the documentation infrastructure (#20080, #20893, #20577).

[embray]

comment:9

See also #21841 -- per that ticket, I think that if Sage's docbuild facilities are made available to third-party code (as I think it should be) then either it should be moved into the sage library itself (i.e. sage.docbuild) or its own package (sage_docbuild)--sage_setup is not otherwise a good place for it.

[embray]

comment:10

I don't fully understand how citations are handled, but would it not be desirable for third-party docs to either have their own citation list, or to be able to point to citations in Sage's docs (if available)?

[mkoeppe]

Description changed:

--- 
+++ 
@@ -2,4 +2,9 @@
 
 `sage -docbuild foo.py`
 
-for a single file not in the library
+for a single file not in the library.
+
+
+See also:
+- https://github.com/mkoeppe/sage-numerical-backends-coin/issues/2
+