Opened 6 years ago

Last modified 4 months ago

#20080 new task

Meta-ticket: Sage docbuild

Reported by: nthiery Owned by:
Priority: major Milestone: sage-9.7
Component: documentation Keywords:
Cc: egourgoulhon, jhpalmieri, dimpase, klee, schilly Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by mkoeppe)

Docbuild tickets:

  • #30010 Split sage_setup.docbuild out to a separate distribution (distutils package)
  • #31353 sage --docbuild: Add options to list all documents
  • #31936 docbuild: Japanese characters creeping into other parts of Sage documentation
  • #31366 docbuild: switch from optparse to argparse
  • #31948 Reimplement parallel docbuild using make
  • #29868 pip-installable packages sage-doc-html, sage-doc-pdf
  • #30369 Parallel docbuild, cythonization: Use GNU make's POSIX jobserver protocol
  • #30475 sage -docbuild: error building docs of single file with relative imports
  • #6389 expose building documentation for user modules not in the Sage library
  • #30418 Missing PDF icons in the Sage documentation website
  • #28376 Shrink Documentation
  • #31415 GH Actions workflow that deploys built documentation
  • #29868 pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf
  • https://github.com/sagemath/documentation/issues/24 (Versioned Sage documentation)

Sphinx tickets:

  • #31696 Sphinx/docutils update for Sage 9.4
  • #27578 Use sphinx.util.inspect.Signature not sphinx.ext.autodoc.inspector.formatargspec
  • #27164 link sphinx docs of Sage components in reference manual
  • #29231 add intersphinx mapping for SciPy
  • #27495 Use sphinx.ext.extlinks to add Sphinx roles for links to external package docs
  • #30893 Replace sage autodoc extension by built-in one
  • #30894 Add typing info to documentation using sphinx_autodoc_typehints

See also:

  • #20893 Meta-ticket: Improve live documentation in the Jupyter notebook

Overview of Sphinx custom code in Sage's documentation build system

The goal of this ticket is to write an overview of the various bits and pieces of custom Sphinx code in Sage, with the long term goal to see which pieces could be:

  • thrown away, using features that are now in Sphinx
  • generalized and submitted upstream
  • cleaned up

Here is a list of files with their relative roles:

src/sage/docs

  • __init__.py: empty file
  • conf.py: standard Sphinx configuration file.

src/sage_docbuild (was src/sage_setup/docbuild)

  • __init__.py: top-level docbuilder, contains classes for the various documents (e.g. reference manual).
  • __main__.py: stub entry point for sage --docbuild, calls main() from __init__.py
  • build_options.py: Parse the option for building.
  • sphinxbuild.py: Sage's version of the sphinx-build script

mainly deals with logging and error reporting.

src/sage_docbuild/ext (was src/sage_setup/docbuild/ext)

  • inventory_builder.py:

A customized HTML builder which only generates intersphinx "object.inv" inventory files and pickle files. The documentation files are not written. This is supposed to be used with multidocs below.

  • multidocs.py:

The goal of this extension is to manage a multi documentation in Sphinx. To be able to compile Sage's huge documentation in parallel, the documentation is cut into a bunch of independent documentations called "subdocs", which are compiled separately. There is a master document which points to all the subdocs. The intersphinx extension ensures that the cross-link between the subdocs are correctly resolved. However some work is needed to build a global index. This is the goal of multidocs.

More precisely this extension ensures the correct merging of

  1. the todo list if this extension is activated;
  2. the python indexes;
  3. the list of python modules;
  4. the javascript index;
  5. the citations.
  • sage_autodoc.py

This is a patched version of sphinx.ext.autodoc, which started to diverge before 2011. As far as I (Florent) understand, the role here is to

  1. allows to correctly fetch the Cython doc and argspec
  2. get correctly the argspec of callable (from the _sage_argspec_ attribute) #9976
  3. deals correctly with LazyImport? #17455
  4. In particular document CachedFunction? as a function and not a class instance #9976.
  5. correctly handles classe aliases and nested classed #7448 #5986

This file probably need to be completely reworked since Sphinx seems to have now various plugin and Mixin.

src/sage/misc

  • sphinxify.py

script which calls Sphinx to format a single docstring for help from the command line or the notebook. Has its own configuration.

Change History (33)

comment:1 Changed 6 years ago by nthiery

  • Description modified (diff)

comment:2 Changed 6 years ago by nthiery

  • Description modified (diff)

comment:3 Changed 6 years ago by hivert

  • Description modified (diff)

comment:4 Changed 6 years ago by jdemeyer

  • Description modified (diff)

comment:5 Changed 6 years ago by jdemeyer

  • Description modified (diff)

comment:6 follow-up: Changed 6 years ago by fbissey

I would like to mention sphinxify.py which is currently part of sagenb but should be moved to inside sage proper ASAP. sphinxify is called from sage/misc/sagedoc.py both at doc building time and run time.

comment:7 Changed 6 years ago by jdemeyer

  • Description modified (diff)

comment:8 Changed 6 years ago by jdemeyer

  • Description modified (diff)

comment:9 Changed 6 years ago by egourgoulhon

  • Cc egourgoulhon added

comment:10 in reply to: ↑ 6 Changed 6 years ago by kcrisman

I would like to mention sphinxify.py which is currently part of sagenb but should be moved to inside sage proper ASAP. sphinxify is called from sage/misc/sagedoc.py both at doc building time and run time.

I'm open to PRs, as this seems pretty reasonable - docbuild shouldn't depend on sagenb, though we would still want the doc to work from within it.

comment:11 Changed 6 years ago by hivert

  • Description modified (diff)

comment:12 Changed 6 years ago by embray

Could someone clarify what

This is a slightly hacked-up version of the Sphinx-multidoc plugin

means?

I can't find any reference to a Sphinx multidoc plugin outside of Sage.

comment:13 Changed 6 years ago by jdemeyer

  • Description modified (diff)

Fixed :-)

comment:14 Changed 6 years ago by jdemeyer

  • Description modified (diff)

comment:15 Changed 6 years ago by embray

I'm having "fun" finally taking the time to fully understand the doc builds system... :)

comment:16 Changed 2 years ago by dimpase

it would be a good idea to revise this, or perhaps just start from scratch. It's not clear to me whether most/all of this can be achieved with vanilla Sphinx 3 or 4.

comment:17 Changed 2 years ago by mkoeppe

Related: #30010 - Split sage_setup.docbuild out to a separate distribution (distutils package)

comment:18 Changed 2 years ago by dimpase

One of sphinx devs, Takeshi KOMIYA, is going to do a comparison with "native" sphinx for the reference manual - https://github.com/sphinx-doc/sphinx/issues/7891

comment:19 Changed 2 years ago by nthiery

Cool!

comment:20 Changed 2 years ago by mkoeppe

  • Cc jhpalmieri dimpase added
  • Description modified (diff)
  • Milestone changed from sage-7.1 to sage-9.3
  • Summary changed from Overview of Sphinx custom code in Sage's documentation build system to Meta-ticket: Sage docbuild

comment:21 Changed 2 years ago by jhpalmieri

  • Description modified (diff)

comment:22 Changed 2 years ago by egourgoulhon

  • Description modified (diff)

comment:23 Changed 18 months ago by mkoeppe

  • Milestone changed from sage-9.3 to sage-9.4

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

comment:24 Changed 18 months ago by mkoeppe

  • Description modified (diff)

comment:25 Changed 14 months ago by mkoeppe

  • Description modified (diff)

comment:26 Changed 14 months ago by mkoeppe

  • Description modified (diff)

comment:27 Changed 14 months ago by mkoeppe

  • Description modified (diff)

comment:28 Changed 14 months ago by mkoeppe

  • Description modified (diff)

comment:29 Changed 14 months ago by mkoeppe

  • Description modified (diff)

comment:30 Changed 12 months ago by mkoeppe

  • Milestone changed from sage-9.4 to sage-9.5

comment:31 Changed 8 months ago by mkoeppe

  • Milestone changed from sage-9.5 to sage-9.6

comment:32 Changed 4 months ago by mkoeppe

  • Cc klee schilly added
  • Description modified (diff)

comment:33 Changed 4 months ago by mkoeppe

  • Milestone changed from sage-9.6 to sage-9.7
Note: See TracTickets for help on using tickets.