= Sphinx = == Description == Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of multiple reStructuredText sources), written by Georg Brandl. It was originally created to translate the new Python documentation, but has now been cleaned up in the hope that it will be useful to many other projects. == License == Modified BSD; see e.g. its egg-info file for other options == SPKG Maintainers == Mike Hansen == Upstream Contact == Author: Georg Brandl Home Page: http://sphinx.pocoo.org, see also http://pypi.python.org/pypi/Sphinx == Dependencies == * Jinja2 >= 2.2 * Pygments >= 0.8 * docutils >= 0.5 * setuptools / distribute * Python * GNU patch (shipped with Sage) == Special Update/Build Instructions == * Make sure to update the Sphinx version number in the file patches/sphinx-build. * Here is a description of patches on top of Sphinx 1.1.2: - patches/autodoc.patch: This patches src/sphinx/ext/autodoc.py. This adds an option to Sphinx to provide a function to get the argspecs of built-in functions. - patches/environment.patch: This patches the file src/sphinx/environment.py. Patching it should prevent Sphinx from rebuilding documentation that is already built. - patches/highlighting.patch: This patches the file src/sphinx/highlighting.py. The patch should allow Sphinx to recognize the Sage prompt "sage:" the same way it recognizes the ">>>" from Python. - patches/pngmath.patch: This replaces \usepackage[utf8x]{inputenc} by \usepackage[utf8]{inputenc} in the LaTeX preamble for building images in the HTML documentation. This change is done because some LaTeX installations have only utf8, not utf8x (utf8x adds support for much more Unicode characters, but these are not needed to typeset the mathematics in the Sage documentation). - patches/Makefile.patch: This patches the file src/sphinx/texinputs/Makefile to increase the save size stack to 50,000 and increase the pool size stack to 4,000,000. These increased stack sizes should be sufficient for LaTeX to handle the huge index of the Sage reference manual when building the PDF version of that manual. * The script create_grammar_pickle.py creates the file Grammar2.7.pickle in site-packages/Sphinx-.../sphinx/pycode/. This helps to avoid race conditions when building the documentation in parallel. * To do: autogenerate the file sage_autodoc.py from src/sphinx/ext/autodoc.py. sage_autodoc.py is currently in SAGE_ROOT/devel/sage/doc/common and is tracked in the Sage library repository, and as a result, it is now somewhat out-of-synch with autodoc.py. Instead we could do the following: in spkg-install, cp sphinx/ext/autodoc.py sphinx/ext/sage_autodoc.py Then patch sage_autodoc.py in place. This would require modifying devel/sage/doc/common/conf.py: 'extensions' would use 'sphinx.ext.sage_autodoc' instead of 'sage_autodoc'. == Changelog == === sphinx-1.1.2.p2 (John Palmieri, 13 February 2013) === * #6495: create the grammar pickle upon installation, by running the script create_grammar_pickle.py. This helps to avoid race conditions when building the documentation in parallel. === sphinx-1.1.2.p1 (Jeroen Demeyer, 28 February 2012) === * #12572: add extra_mem_top=2000000 to the environment when running latex. This increases the amount of main memory available. === sphinx-1.1.2.p0 (John Palmieri, November 5th 2011) === * #10620: Upgrade to Sphinx 1.1.2. Also minor editing of SPKG.txt. === sphinx-1.0.8.p0 (John Palmieri, September 23rd 2011) === * #10620: Upgrade to Sphinx 1.0.8. === sphinx-1.0.4.p8 (Leif Leonhardy, August 17th 2011) === * #11665: Don't delete previously built Sage documentation (in $SAGE_ROOT/devel/sage-*/doc/output/) until Sphinx has been successfully reinstalled. * Also, don't delete a previous Sphinx installation until Sphinx has been successfully (re)built. To achieve this, we now first run 'python setup.py build', then delete any previously installed version, and after that run 'python setup.py install'. * Quote the filename of patches. * Some clean-up, add some messages (and blank lines to separate the output). * Added some more of Sphinx' dependencies, corrected minimal version numbers required. === sphinx-1.0.4.p7 (Jeroen Demeyer, 2011-08-08) === * Ticket #11659: Increase LaTeX SAVE_SIZE from 20000 to 50000 === sphinx-1.0.4.p6 (Jeroen Demeyer, 2011-01-31) === * Ticket #10721: Double LaTeX POOL_SIZE to 40000000 === sphinx-1.0.4.p5 (Jeroen Demeyer, 2010-12-05) === * Ticket #10350: Fix some remaining issues with sphinx-1.0.4.p3.spkg * Redirect standard input of (pdf)latex from /dev/null, to avoid latex hanging with messages like ! LaTeX Error: File `titlesec.sty' not found. Type X to quit or to proceed, or enter new name. (Default extension: sty) * Create and apply patches according to #9419. * Fix some typos. === sphinx-1.0.4.p3 (Jeroen Demeyer, 2010-11-18) === * Use env instead of export for environment variables in Makefile. * More error checking in spkg-install. * Use patch instead of cp for patching files. * Move the patch src/sphinx/writers/latex.py to doc/common/conf.py in the Sage library. * Simplified highlighting.patch by moving the highlighting of the "sage:" prompt to the Pygments spkg (#10290). Now the highlighting.patch is only needed to recognize the Sage prompt. * Add patch for sphinx/ext/pngmath.py to use the utf8 encoding instead of utf8x. === sphinx-1.0.4.p0 (Minh Van Nguyen, 2010-11-05) === * Ticket #10118: upgrade to upstream Sphinx version 1.0.4. * Describe all patches on top of Sphinx 1.0.4. * Change patches/sphinx-build to require Sphinx 1.0.4 since we are now using Sphinx 1.0.4. * Legacy patch -- Patch the file src/sphinx/environment.py, which is part of Sphinx 1.0.4. Patching it should prevent Sphinx from rebuilding documentation that is already built. This patch is a carry over from the previous sphinx-0.6.3.p4 package. * Legacy patch -- Patch the file src/sphinx/highlighting.py. The patch should allow Sphinx 1.0.4 to perform special highlighting of the Sage prompt "sage:". That is, treat the Sage prompt "sage:" like the way Sphinx treats the Python prompt ">>>". This patch is a carry over from the previous sphinx-0.6.3.p4 package. * Legacy patch -- Patch src/sphinx/ext/autodoc.py. This adds an option to Sphinx to provide a function to get the argspecs of built-in functions. * New patch -- Patch src/sphinx/writers/latex.py to prevent Sphinx from by default inserting the following LaTeX declaration into the preamble of a .tex file: \DeclareUnicodeCharacter{00A0}{\nobreakspace} This declaration is known to result in a failure to build the PDF version of a document in the Sage standard documentation. See ticket #8183 for further information on this issue. * New patch -- Patch the file src/sphinx/texinputs/Makefile to increase the save size stack to 20,000 and increase the pool size stack to 2,000,000. These increased stack sizes should be sufficient for LaTeX to handle the huge index of the Sage reference manual when building the PDF version of that manual. * In spkg-install, put all the patching commands into the new function apply_patch(). === 0.6.3.p4 (Minh Van Nguyen, 2009-12-31) === * Patch src/sphinx/environment.py to prevent Sphinx from rebuilding a document again. Once a document is built and we make changes to it, Sphinx should not rebuild the full document, but only portion(s) of the document that have changed. The patch for src/sphinx/environment.py was suggested by Mitesh Patel. === 0.6.3.p3 (Mike Hansen, 2009-12-15) === * Add an option to Sphinx to provide a function to get the argspecs of built-in functions. === 0.6.3.p2 (Tim Dumol, 2009-10-25) === * Modify spkg-install to delete `doc/output` folders, to fix #7286. === 0.6.3.p1 (John Palmieri, 2009-09-04) === * Modify spkg-install, in line with the ideas at http://trac.sagemath.org/sage_trac/ticket/6598 and http://wiki.sagemath.org/DavidKirkby === 0.6.3 (John Palmieri, 2009-09-03) === * Updated to version 0.6.3 === 0.5.1 (Mike Hansen, December 16th, 2008) === * Updated to version 0.5.1 * Made sure that sphinx-build.py imported sage.all at the beginning === 0.5 (Mike Hansen, December 1st, 2008) === * Updated to version 0.5 === svn 66476 (Mike Hansen, September 15th, 2008) === * Initial version.