making docstrings using sphinx -- need a bit of help

asked 2012-10-01 06:29:46 +0200

SLOtoSF gravatar image

updated 2012-10-01 07:42:51 +0200


I've done the following:

1) Downloaded `sudo apt-get install python-setuptools

2) Downloaded easy_install -U sphinx then navigated to my project directory ...sage/<project-name>

3) Ran sage -sh and sphinx-quickstart and followed the defaults except I chose separate directories for my build and source files.

4) Ran make latex andmake latexpdf

It's blank! Please advise.

How can I ensure it picks up certain .py files? Any tips?

edit retag flag offensive close merge delete


I don't have an answer per se, but I'll note that sphinx itself probably only picks up .rst files. I don't know how Sage "converts" its .py to .rst files, but I think we have something that does this. When I've used this workflow, I only had .rst files to contend with.

kcrisman gravatar imagekcrisman ( 2012-10-01 09:16:15 +0200 )edit

Sphinx is already installed as part of Sage, so I think you can skip steps 1 and 2.

John Palmieri gravatar imageJohn Palmieri ( 2012-10-01 11:27:15 +0200 )edit

@John Palmieri I can't seems to find anything on the online documentation.

SLOtoSF gravatar imageSLOtoSF ( 2012-10-01 14:28:33 +0200 )edit

When you install Sage, there is a file `SAGE_ROOT/local/bin/sphinx-quickstart`, for example, as well as Python files in `SAGE_ROOT/local/lib/python/site-packages/Sphinx-1.1.2-py2.7.egg/sphinx/`. The former will be run if you do `sage -sh` and then `sphinx-quickstart`.

John Palmieri gravatar imageJohn Palmieri ( 2012-10-01 14:48:33 +0200 )edit

I think that many of the components of Sage are not explicitly documented in the Sage documentation, like gap, Singular, matplotlib, etc. Sphinx is no different, but it should be at least suggestive that the bottom of every page of Sage documentation says "Created using Sphinx 1.1.2."

John Palmieri gravatar imageJohn Palmieri ( 2012-10-01 14:50:52 +0200 )edit