| | 2 | |
| | 3 | The patch is large, but most of it consists of moving files from one location to another, as described below. A summary of the changes: |
| | 4 | |
| | 5 | Changes in `doc/en/reference` — this is where the size of the patch comes from, although the changes are pretty simple: |
| | 6 | |
| | 7 | - rearrange the directory doc/en/reference: for each file like algebras.rst, create a subdirectory `algebras` and move `algebras.rst` to `algebras/index.rst`. Also create a file `algebras/conf.py` for the build configuration. All of these new conf.py files are identical. Deal with the contents of the directory `reference/media` similarly, moving the pictures to the appropriate subdirectory. |
| | 8 | - modify `reference/index.rst` to point to these new files. |
| | 9 | - reorganize `reference/index.rst` so it is arranged, at least somewhat, by topic. |
| | 10 | - add intersphinx to `conf.py` — see below. Also add the new subdirectories to the list `exclude_trees`. |
| | 11 | - new file `conf_sub.py`, configuration for the pieces of the documentation (as opposed to the main `conf.py`, which is for building `reference/index.rst`). This file is imported by each of the files `SUBDIRECTORY/conf.py`. |
| | 12 | |
| | 13 | Changes to `doc/common/builder.py`: |
| | 14 | |
| | 15 | - add code to build the reference manual in sections, and also to build the sections in parallel. The reference manual ought to be built twice to resolve references now, so typing "sage -docbuild all html" will build it twice (along with all of the other documents, of course). "sage -docbuild reference html" will just build it once. You can also run "sage -docbuild reference/combinat html", for example, to just build one part of the manual. |
| | 16 | - the different parts of the manual are separate documents as far as sphinx is concerned, so allow them to reference each other using the "intersphinx" extension. (This is why we need to build it twice: the first pass assembles the intersphinx databases, the second pass uses the databases to create the references correctly.) |
| | 17 | - to accomodate the changes in #11251, which don't seem to be easily compatible with intersphinx, search through the output files looking for "todo" items, and accumulate them in one master "todo" list. |
| | 18 | - for pdf format, since it now produces 30 different pdf files, write an html file which links to each of them. |
| | 19 | |
| | 20 | Other changes: |
| | 21 | |
| | 22 | - `doc/common/conf.py`: add the intersphinx extension to the build process. |
| | 23 | - `doc/common/themes/sage/layout.html`: fix a bug where clicking the Sage logo in the upper left corner of the docs wouldn't take you to the right place, at least in the local documentation. |
| | 24 | - `doc/common/themes/sageref/`: add a new theme for the pieces of the reference manual. This is almost identical to the "sage" theme, except for a little tinkering to the links along the top and bottom lines. |
| | 25 | - in the main Sage library, change a few pathnames to media files in the reference manual, since those files have been moved. |
| | 26 | - `spkg-dist`: when building the main sage spkg file, delete all of the autogenerated files from the doc directory. This is important because if some autogenerated files from before the patch are still present after the patch, the docbuild process can occasionally get confused. It also saves some space, making a smaller spkg file. |
| | 27 | - make the necessary changes to .hgignore and MANIFEST.in to deal with the relocated files. |
| | 28 | |
| | 29 | -------- |
