Sage multidocs extension - Documentation System

Skip to content
Back to top
View this page
Edit this page

# 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.