Sage multidocs extension#

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 “sub-docs”, which are compiled separately. There is a master document which points to all the sub-docs. The intersphinx extension ensures that the cross-link between the sub-docs are correctly resolved. However some work is needed to build a global index. This is the goal of the multidocs extension.

More precisely this extension ensures the correct merging of

  • the todo list if this extension is activated

  • the python indexes

  • the list of python modules

  • the javascript index

  • the citations

sage_docbuild.ext.multidocs.citation_dir(app)#
sage_docbuild.ext.multidocs.fetch_citation(app, env)#

Fetch the global citation index from the refman to allow for cross references.

sage_docbuild.ext.multidocs.fix_path_html(app, pagename, templatename, ctx, event_arg)#

Fix the context so that the files

  • search.html

  • genindex.html

  • py-modindex.html

point to the right place, that is in reference/ instead of reference/subdocument.

sage_docbuild.ext.multidocs.get_env(app, curdoc)#

Get the environment of a sub-doc from the pickle

sage_docbuild.ext.multidocs.get_js_index(app, curdoc)#

Get the JS index of a sub-doc from the file

sage_docbuild.ext.multidocs.init_subdoc(app)#

Init the merger depending on if we are compiling a sub-doc or the master doc itself.

sage_docbuild.ext.multidocs.merge_environment(app, env)#

Merge the following attributes of the sub-docs environment into the main environment:

  • titles – Titles

  • todo_all_todos – todo’s

  • indexentries – global python index

  • all_docs – needed by the js index

  • citations – citations

  • domaindata['py']['modules'] – list of python modules

sage_docbuild.ext.multidocs.merge_js_index(app)#

Merge the JS indexes of the sub-docs into the main JS index

sage_docbuild.ext.multidocs.setup(app)#
sage_docbuild.ext.multidocs.write_citations(app, citations)#

Pickle the citation in a file.