Adds Abelian sandpile model to the reference manual

[dcoudert]

There is a nice thematic tutorial on Sandpiles (http://www.sagemath.org/doc/thematic_tutorials/sandpile.html), but the functions are not included in the reference manual. This is the goal of this patch.

CC: @sagetrac-dperkinson

Component: documentation

Keywords: sandpile

Author: David Coudert

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

[dcoudert]

comment:1

I'm unable to build the documentation :( Any help to find the missing instructions is more than welcome.

[dcoudert]

Description changed:

--- 
+++ 
@@ -1,2 +1,2 @@
-There is a nice thematic tutorial on Sandpiles (http://www.sagemath.org/doc/thematic_tutorials/sandpile.html), but the functions are not included in the reference manual. This is done by this patch.
+There is a nice thematic tutorial on Sandpiles (http://www.sagemath.org/doc/thematic_tutorials/sandpile.html), but the functions are not included in the reference manual. This is the goal of this patch.

[bc92013b-9220-40da-a45f-06c52942e68d]

comment:2

I was unable to apply the patch. Running hg_sage.apply('trac_13342-adds-sandpile-to-reference-manual.patch') produced an error:

sage: hg_sage.apply('/home/davidp/downloads/trac_13342-adds-sandpile-to-reference-manual.patch') cd "/usr/local/sage/devel/sage" && sage --hg import "/home/davidp/downloads/trac_13342-adds-sandpile-to-reference-manual.patch" applying /home/davidp/downloads/trac_13342-adds-sandpile-to-reference-manual.patch unknown exception encountered, please report by visiting http://mercurial.selenic.com/wiki/BugTracker Python 2.7.3 (default, Jul 9 2012, 15:05:17) [GCC 4.6.3] Mercurial Distributed SCM (version 1.8.4) ** Extensions loaded: color, mq, pager, rebase, relink Traceback (most recent call last): File "/usr/local/sage/local/bin/hg", line 38, in mercurial.dispatch.run()

<------- snip ------------->

File "/usr/local/sage/local/lib/python/mercurial/patch.py", line 983, in scangitpatch gitpatches = readgitpatch(gitlr) File "/usr/local/sage/local/lib/python/mercurial/patch.py", line 339, in readgitpatch gp.setmode(int(line[-6:], 8)) ValueError: invalid literal for int() with base 8: ''

I don't know if this is a problem with sage or a problem with the patch.

[bc92013b-9220-40da-a45f-06c52942e68d]

comment:3

Replying to @dcoudert:

I'm unable to build the documentation :( Any help to find the missing instructions is more than welcome.

Do you mean that

sage -docbuild reference html

does not work? I read about making the document in the installation guide. You can also enter

sage -docbuild -H

to see all the options.

[dcoudert]

comment:4

I don't use the hg_sage.apply('...') function to apply a patch but

sage -hg qimport some_patch.patch
sage -hg qpush
sage -b
...

Currently the patch has no effect when running:

sage -docbuild reference html

The objective is to build a reference page for sandpiles, as for all other modules in sage.

Most probably, I'm missing some informations in some .rst or .py file, but I don't know which one :(

Let's hope someone will be able to find the solution.

[jdemeyer]

comment:5

Why are you changing setup.py?

[dcoudert]

comment:6

When I was trying to build this documentation, I did some cleaning to setup.py, but you are right this should not be in this patch. I will remove it.

I still don't know what's missing for building the documentation.

When I run trying to build the documentation, I got the following message. It builds a page sandpiles.html, but it is empty :(

ompote:/path-to-sage/sage-5.3.beta0/devel/sage> ../../sage -docbuild reference html                                                        
sphinx-build -b html -d /path-to-sage/sage-5.3.beta0/devel/sage/doc/output/doctrees/en/reference    /path-to-sage/sage-5.3.beta0/devel/sage/doc/en/reference /path-to-sage/sage-5.3.beta0/devel/sage/doc/output/html/en/reference
Running Sphinx v1.1.2
loading pickled environment... done
loading intersphinx inventory from /path-to-sage/sage-5.3.beta0/devel/sage/doc/common/python.inv...
building [html]: targets for 2 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
reading sources... [ 50%] index
reading sources... [100%] sandpiles

/path-to-sage/sage-5.3.beta0/devel/sage/doc/en/reference/sandpiles.rst:4: WARNING: toctree contains reference to nonexisting document u'sage/sandpiles/sandpile'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 50%] index
writing output... [100%] sandpiles

writing additional files... genindex py-modindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.
Build finished.  The built documents can be found in /path-to-sage/sage-5.3.beta0/devel/sage/doc/output/html/en/reference

[dcoudert]

Without touching file setup.py

[jdemeyer]

comment:7

Attachment: trac_13342-adds-sandpile-to-reference-manual.patch.gz

[fchapoton]

comment:11

They are now included in the doc.

http://doc.sagemath.org/html/en/reference/dynamics/index.html