Files

= 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 <mhansen@gmail.com>

== Upstream Contact ==

Author: Georg Brandl <georg at python org>
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 <RETURN> 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.