Update Sphinx to 1.4.1

[a-andre]

Changes: http://sphinx-doc.org/changes.html

Tarballs:

• https://pypi.python.org/packages/source/i/imagesize/imagesize-0.7.0.tar.gz
• https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.1.tar.gz
• https://pypi.python.org/packages/6e/65/3b15c248e4078278a7c9d45ecac2b87ae56f03dfb574e6ee31edea360fdd/alabaster-0.7.7.tar.gz
• https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz

Depends on #20496 Depends on #20498

CC: @kiwifb

Component: packages: standard

Keywords: days77

Author: André Apitzsch, Jeroen Demeyer

Branch/Commit: bdc3f0b

Reviewer: Steven Trogdon, John Palmieri

Issue created by migration from https://trac.sagemath.org/ticket/18497

[jhpalmieri]

comment:41

I don't know the right fix, but I think the problem is in this line:

diff --git a/src/sage_setup/docbuild/__init__.py b/src/sage_setup/docbuild/__init__.py
index 6bfe38e..069c0a9 100644
--- a/src/sage_setup/docbuild/__init__.py
+++ b/src/sage_setup/docbuild/__init__.py
@@ -767,7 +767,7 @@ class ReferenceSubBuilder(DocBuilder):

         env_pickle = os.path.join(self._doctrees_dir(), 'environment.pickle')
         try:
-            env = BuildEnvironment.frompickle(config, env_pickle)
+            env = BuildEnvironment.frompickle(self.dir, config, env_pickle)
             logger.debug("Opened Sphinx environment: %s", env_pickle)
             return env
         except IOError as err:

With this change I get other errors, one of which can be fixed like this:

diff --git a/src/sage_setup/docbuild/ext/sage_autodoc.py b/src/sage_setup/docbuild/ext/sage_autodoc.py
index 20f7168..e2073a5 100644
--- a/src/sage_setup/docbuild/ext/sage_autodoc.py
+++ b/src/sage_setup/docbuild/ext/sage_autodoc.py
@@ -38,7 +38,7 @@ from sphinx.application import ExtensionError
 from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.compat import Directive
 from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \
-     safe_getattr, safe_repr as sphinx_safe_repr, is_builtin_class_method
+     safe_getattr, object_description as sphinx_safe_repr, is_builtin_class_method
 from sphinx.util.pycompat import base_exception, class_types
 from sphinx.util.docstrings import prepare_docstring

I don't know about the others, though.

[strogdon]

comment:42

Also, sphinx still tries to load alabaster even though it is not installed because of no_alabaster.patch. In Sphinx-1.4/sphinx/application.py there is

        # for now, sphinx always load a 'alabaster' extension.
        if 'alabaster' not in self.config.extensions:
            self.config.extensions.append('alabaster')

[jdemeyer]

Changed keywords from none to days77

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from ba6c218 to 4d79d4b

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

4d79d4b

Fix frompickle() call

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 4d79d4b to 55b17c7

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

55b17c7

Trivial autodoc changes

[jhpalmieri]

comment:46

Replying to @strogdon:

Also, sphinx still tries to load alabaster even though it is not installed because of no_alabaster.patch.

Right, I guess that's what I meant by "other errors".

[strogdon]

comment:47

So, using MAKE=make -j1 the first failures/warnings are:

[repl     ] /64bitdev/storage/sage-git_develop/sage/src/doc/en/reference/repl/sage/repl/display/fancy_repr.rst:13: WARNING: don't know which module to import for autodocumenting u'__call__' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
[repl     ] /64bitdev/storage/sage-git_develop/sage/src/doc/en/reference/repl/sage/repl/display/fancy_repr.rst:23: WARNING: don't know which module to import for autodocumenting u'__call__' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
[repl     ] /64bitdev/storage/sage-git_develop/sage/src/doc/en/reference/repl/sage/repl/display/fancy_repr.rst:53: WARNING: don't know which module to import for autodocumenting u'__call__' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
[repl     ] /64bitdev/storage/sage-git_develop/sage/src/doc/en/reference/repl/sage/repl/display/fancy_repr.rst:69: WARNING: don't know which module to import for autodocumenting u'__call__' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
[repl     ] /64bitdev/storage/sage-git_develop/sage/src/doc/en/reference/repl/sage/repl/display/fancy_repr.rst:79: WARNING: don't know which module to import for autodocumenting u'__call__' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
[repl     ] /64bitdev/storage/sage-git_develop/sage/src/doc/en/reference/repl/sage/repl/display/util.rst:15: WARNING: don't know which module to import for autodocumenting u'__call__' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

And all occur where there is

    .. automethod:: __call__

which is the same type of error we had way back when. So what's the fix - to include the class name with the method name?

[jdemeyer]

Changed dependencies from #20359, #14840 to #20359, #14840, #20389

[jdemeyer]

comment:49

I am working on this, hang on...

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 55b17c7 to 4444661

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

d3d8726	Use ref_context instead of temp_data
d87a8b9	Fix citation warnings in the first docbuild pass
5eea54e	Fix documentation formatting
4444661	Merge commit '5eea54e3e8c7d9117600a0a2020b881c1415b93f' into t/18497/ticket/18497

[strogdon]

comment:51

I see. That's the way it is in the Sphinx autodoc.py.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

046b815	update sphinx package to 1.3.1
e6a83ce	fix some deprecation warnings
8f26547	fix orphan setting
490b1ba	fix warning "more than one target found for cross-reference u'groebner_basis'"
2e872d8	trac 18497: in docbuilding, use exclude_patterns instead of exclude_trees.
6202e0f	Upgrade to Sphinx 1.4
88ab0b8	Fix frompickle() call
fccac05	Trivial autodoc changes
7b7a233	Use ref_context instead of temp_data
73aca63	Fix citation warnings in the first docbuild pass

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 4444661 to 73aca63

[jdemeyer]

Changed dependencies from #20359, #14840, #20389 to none

[jdemeyer]

Description changed:

--- 
+++ 
@@ -5,4 +5,4 @@
 Tarballs:
 * [https://pypi.python.org/packages/source/i/imagesize/imagesize-0.7.0.tar.gz](https://pypi.python.org/packages/source/i/imagesize/imagesize-0.7.0.tar.gz)
 * [https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.1.tar.gz](https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.1.tar.gz)
-* [https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.tar.gz](https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.tar.gz)
+* [https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz](https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz)/S/Sphinx/Sphinx-1.4.tar.gz]

[jdemeyer]

Description changed:

--- 
+++ 
@@ -1,8 +1,6 @@
-Upgrade to Sphinx 1.4
-
 Changes: http://sphinx-doc.org/changes.html

 Tarballs:
 * [https://pypi.python.org/packages/source/i/imagesize/imagesize-0.7.0.tar.gz](https://pypi.python.org/packages/source/i/imagesize/imagesize-0.7.0.tar.gz)
 * [https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.1.tar.gz](https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.1.tar.gz)
-* [https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz](https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz)/S/Sphinx/Sphinx-1.4.tar.gz]
+* [https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz](https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz)

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 73aca63 to 3f44a48

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:

e19c9cd	update sphinx package to 1.3.1
687b8d0	fix some deprecation warnings
e830471	fix orphan setting
f14cee0	trac 18497: in docbuilding, use exclude_patterns instead of exclude_trees.
c4bc6ec	Upgrade to Sphinx 1.4.1
77f2e25	Use object_description() instead of safe_repr()
8fbd81c	Fix frompickle() call
4899d1b	Use ref_context instead of temp_data
dd122ec	Merge titles
3f44a48	Remove warnings while setting up extensions

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

0bf4475

Remove some warnings

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 3f44a48 to 0bf4475

[jdemeyer]

Dependencies: #20488

[strogdon]

comment:59

The html-docs do build once I deal with alabaster.

[tensor_fr] Extension error:
[polynomia] Extension error:
[repl     ] Extension error:
[tensor_fr] Could not import extension alabaster (exception: No module named alabaster)

It seems to me that that either alabaster must be included as a package or it must be neutered (see comment:42). Also there is a typo in /build/pkgs/sphinx/patches/Makefile.patch, epdflatex should be pdflatex which halts building of the latex-docs.

[strogdon]

comment:60

I might add that I find it amazing how this has progressed. Initially it was a nightmare.

[jdemeyer]

comment:61

The generated documentation doesn't look bad either, there is not much difference with the old version. One thing I noticed is that the sage: prompts are no longer syntax highlighted in a special way. This is probably a bug, in any case it makes the documentation look more boring.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

59e9128	Use exclude_patterns instead of exclude_trees
ec99297	Upgrade to Sphinx 1.4.1
a4ac4bd	Use object_description() instead of safe_repr()
4fcca56	Fix frompickle() call
1b2f057	Use ref_context instead of temp_data
cbe7b8a	Merge titles
fefe126	Remove some warnings

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 0bf4475 to fefe126

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from fefe126 to e26d349

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

e26d349

Fix syntax highlighting

[strogdon]

comment:64

Perhaps getting a bit ahead but if I force building the pdf-docs I get

                $
l.6285 \($\prod
               _j=1^{i-1} m_j^{-1} (mod m_i)$\)

which seems to come from

local/share/doc/sage/latex/en/reference/rings_standard/rings_standard.tex

The associated math formulas in

local/share/doc/sage/html/en/reference/rings_standard/sage/ext/multi_modular.html

don't look correct.

WikiFormatting is not working properly for me here. I can't get what I want inside a {{{...}}}

[jhpalmieri]

comment:65

Is this the formula on line 710 of multi_modular.pyx? That looks like it has extra backticks or dollar signs: the formula should have one or the other, not both.

[jdemeyer]

Description changed:

--- 
+++ 
@@ -3,4 +3,5 @@
 Tarballs:
 * [https://pypi.python.org/packages/source/i/imagesize/imagesize-0.7.0.tar.gz](https://pypi.python.org/packages/source/i/imagesize/imagesize-0.7.0.tar.gz)
 * [https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.1.tar.gz](https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.1.tar.gz)
+* [https://pypi.python.org/packages/6e/65/3b15c248e4078278a7c9d45ecac2b87ae56f03dfb574e6ee31edea360fdd/alabaster-0.7.7.tar.gz](https://pypi.python.org/packages/6e/65/3b15c248e4078278a7c9d45ecac2b87ae56f03dfb574e6ee31edea360fdd/alabaster-0.7.7.tar.gz)
 * [https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz](https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.4.1.tar.gz)

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:

1d1a55e	fix some deprecation warnings
ad77f32	fix orphan setting
0c2d32b	Use exclude_patterns instead of exclude_trees
8994b2e	Upgrade to Sphinx 1.4.1
d8bd358	Use object_description() instead of safe_repr()
eb4b263	Fix frompickle() call
496b284	Use ref_context instead of temp_data
e16162f	Merge titles
039dd29	Remove some warnings
7c2d9d5	Fix syntax highlighting

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from e26d349 to 7c2d9d5

[jdemeyer]

comment:68

Replying to @strogdon:

Also, if alabaster is not needed then sphinx will have to be patched to prevent it from being imported.

I fixed this problem by simply installing alabaster. It's a small package, so it's not worth the trouble to patch Sphinx for it. Also, while Sage doesn't use alabaster, maybe other packages do use it.

[strogdon]

comment:69

Replying to @jhpalmieri:

Is this the formula on line 710 of multi_modular.pyx? That looks like it has extra backticks or dollar signs: the formula should have one or the other, not both.

Yes, that's it. And there is a similar problem in src/sage/symbolic/expression.pyx around line 8830.

 There are two square roots of `$(x + 1)^2$`

It appears this version of Sphinx is exposing some sphinx syntax issues in the documentation that now appear when generating the latex files for building the pdf-docs. The older sphinx -> latex must be a bit more forgiving.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 7c2d9d5 to f1ae5e6

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

f1ae5e6

Fix doctest failures with Sphinx 1.4.1

[jdemeyer]

comment:71

Replying to @strogdon:

Yes, that's it. And there is a similar problem in src/sage/symbolic/expression.pyx around line 8830.

Feel free to add commits to fix such issues. I will stop rebasing this branch to make it easier for other people to push fixes.

Sage now builds and all doctests pass with this branch. On first sight, the documentation looks good too.

[strogdon]

comment:72

Also, I see two of

! LaTeX Error: Lonely \item--perhaps a missing list environment.

in docpdf.log. After grepping through latex/en/reference it's because of combinat/combinat.tex and graphs/graphs.tex where there is

}, \footnote[2]{\sphinxAtStartFootnote%\begin{enumerate}
\setcounter{enumi}{4}
\item {}
Assmus, J. Key, Designs and their codes, CUP, 1992.

\end{enumerate}

I suspect this should be

}, \footnote[2]{\sphinxAtStartFootnote%
\begin{enumerate}
\setcounter{enumi}{4}
\item {}
Assmus, J. Key, Designs and their codes, CUP, 1992.

\end{enumerate}

which does work. And since this is auto-generated, I suspect a bug?

[jdemeyer]

comment:73

Replying to @strogdon:

And since this is auto-generated, I suspect a bug?

The real problem is that docutils interprets this as a list item (and that's a feature!):

E. Assmus, J. Key, Designs and their codes, CUP, 1992.

This should work:

-.. [2] E. Assmus, J. Key, Designs and their codes, CUP, 1992.
+.. [2] \E. Assmus, J. Key, Designs and their codes, CUP, 1992.

[jdemeyer]

comment:74

See #20496 for this.

[jdemeyer]

Changed dependencies from #20488 to #20496

[jdemeyer]

Changed dependencies from #20496 to #20496, #20498

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from f1ae5e6 to e88c802

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

e88c802

Fix malformatted mathematics

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

00722fd	Escape abbreviated first names in references
d92eada	Add documentation
54d3cf8	Clean up multi_modular.pyx
ae6192a	Move multi_modular to arith
bdc3f0b	Merge commit 'd92eadade4c3b6a477a14809adeac3c058458ad3'; commit 'ae6192a2a300f7fb7a1bae3dd8034e4d24767428' into t/18497/ticket/18497

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from e88c802 to bdc3f0b