sagemath / sage_sample Goto Github PK

Again, on Sage debian package (sagemath:amd64 8.6-5)

(sage-sh) $ make doc
cd docs && sage -sh -c "make html"
make[1] : on entre dans le répertoire « /home/odile/prj/sage_sample/docs »
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.8.3

Extension error:
Could not import extension sage_autodoc (exception: No module named sage_autodoc)

Some things in this repository could be updated I think. There's also a bunch of pending pull requests. What's the process of merging things here? Should just anybody with permissions press the merge button? Or does @VivianePons review things?

Most of the files created by the sdist command should actually not be there

$ sage -python setup.py sdist
/opt/sage/local/lib/python2.7/site-packages/setuptools/dist.py:333: UserWarning: Normalizing '0.1.0
' to '0.1.0'
  normalized_version,
running sdist
running egg_info
writing sage_sample.egg-info/PKG-INFO
writing top-level names to sage_sample.egg-info/top_level.txt
writing dependency_links to sage_sample.egg-info/dependency_links.txt
writing manifest file 'sage_sample.egg-info/SOURCES.txt'
running check
creating sage_sample-0.1.0
creating sage_sample-0.1.0/docs
creating sage_sample-0.1.0/docs/source
creating sage_sample-0.1.0/sage_sample
creating sage_sample-0.1.0/sage_sample.egg-info
copying files to sage_sample-0.1.0...
copying .gitignore -> sage_sample-0.1.0
copying .travis-deploy-doc.sh -> sage_sample-0.1.0
copying .travis-install.sh -> sage_sample-0.1.0
copying .travis-test.sh -> sage_sample-0.1.0
copying .travis.yml -> sage_sample-0.1.0
copying .travis_ci_gh_pages_deploy_key.enc -> sage_sample-0.1.0
copying LICENSE -> sage_sample-0.1.0
copying README -> sage_sample-0.1.0
copying README.rst -> sage_sample-0.1.0
copying VERSION -> sage_sample-0.1.0
copying makefile -> sage_sample-0.1.0
copying setup.py -> sage_sample-0.1.0
copying docs/Makefile -> sage_sample-0.1.0/docs
copying docs/source/conf.py -> sage_sample-0.1.0/docs/source
copying docs/source/index.rst -> sage_sample-0.1.0/docs/source
copying docs/source/ultimate_question.rst -> sage_sample-0.1.0/docs/source
copying sage_sample/__init__.py -> sage_sample-0.1.0/sage_sample
copying sage_sample/ultimate_question.py -> sage_sample-0.1.0/sage_sample
copying sage_sample.egg-info/PKG-INFO -> sage_sample-0.1.0/sage_sample.egg-info
copying sage_sample.egg-info/SOURCES.txt -> sage_sample-0.1.0/sage_sample.egg-info
copying sage_sample.egg-info/dependency_links.txt -> sage_sample-0.1.0/sage_sample.egg-info
copying sage_sample.egg-info/top_level.txt -> sage_sample-0.1.0/sage_sample.egg-info
Writing sage_sample-0.1.0/setup.cfg
Creating tar archive
removing 'sage_sample-0.1.0' (and everything under it)

The issue can be fixed by dropping setuptools in favor of distutils.

Requires:

• Figuring a way to mock sage modules so that the Python code can be loaded into Python for Sphinx's instrospection
• Making it possible to use, or not, mathjax and theme files provided by Sage

This would enable trivial ReadTheDocs integration #6; but maybe it's not worth the effort and one should take the alternative route described there.

Looking at other projects, this feels more standard, and it reduces the depth by one. But I might be biased.

https://readthedocs.org/ can be a nice way for sage packages to make their documentation available. So it would be nice to investigate how to showcase how to do this in sage_sample.

A first attempt is here: https://readthedocs.org/projects/sage-sample/

As expected, the difficulty is that compiling the documentation with Sphinx requires importing the Sage library. So we need to figure out a way to specify that Sage is a dependency (see readthedocs's build process). At this stage, we can't do it in setup.py.

There also are some ressource limitations; but as long as we do a binary install of Sage, that should not be a problem (unless they have also a disk space limitation).

cc: @embray

Testing sage_sample installation on debian, with the debian package (sagemath:amd64 8.6-5 )

$ sage -sh
(sage-sh) odile@cecile:sage_sample$ sage -pip install --upgrade --no-index -v .
sage-run received unknown option: -pip
usage: sage [options]
Try 'sage -h' for more information.

So I had to do:

$ sage -python2 -m pip install --upgrade --no-index -v .

(which btw is not really documented)

When you "make html" within the ./docs subdirectory, you get a warning:

--%<
copying static files... WARNING: html_static_path entry u'/home/odile/odk/sage/git/sage_sample/docs/source/_static' does not exist
--%<

This warning would disappear if you change line #167 in file ./docs/source/conf.py

#html_static_path = ['_static']
html_static_path = []

As CSS file is not actually required ..

This sample seems to focus on packaging pure Python code. I mainly used Sage packaging to package some programs written in different languages, that were then compiled and copied to $SAGE_LOCAL/bin. I don't see how this can be achieved with the technique explained in this sample.

In #8 the possibility to make the documentation visible on GitHub pages was added, however this was done using custom bash scripts. Travis also has a build in mechanism for deploying documentation to GitHub pages. This seems much cleaner and removes the need of deployment keys.

If I try to use the .. PLOT: directive in docstrings, I get:

 ERROR: Unknown directive type "PLOT".

See: http://www.sphinx-doc.org/en/master/setuptools.html

This could be one way to save duplication between setup.py and conf.py.
An alternative way would be to use the trick in section "Documentation with Sphinx"
from https://jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/

To check: support by e.g. ReadTheDocs

Hi, I think there is something wrong with the encrypted key / deploy key of this repo. I fixed all problems in my own fork. But I cannot do that in this repo since, even though I have write acces, I don't have the right to add a new deploy key. I guess you need to be admin for that.

I am willing to do the needed key generation and encryption and commit it to the correct branches. Is there anyone where I can send the public key to so that it can be added as a deploy key?

binder is a neat web service that gives interactive access to the Jupyter notebooks stored in a GitHub repository. It would be neat to showcase how to include demo notebooks in the package that users can immediately play with on mybinder.

Prerequisite: sagemath/docker-images#23

Please refer to https://packaging.python.org/ instead of the outdated http://python-packaging.readthedocs.io/en/latest/index.html in the README file.

In the makefile, shouldn't the target uninstall be
$(SAGE) -pip uninstall PACKAGE
instead of
$(SAGE) -pip uninstall .
?

$ sage -python2 -m pip install --upgrade --no-index -v .
...
Running command python setup.py egg_info
...
DistributionNotFound: No matching distribution found for sage-package (from sage-sample==0.3.0)

CookieCutter is a wizard-style command line utility that lets users initialize new projects from project templates, after asking a couple questions.

It would be great to have a project template for Sage projects, supporting various use cases:

• Trivial project with a single .sage file
• Project with a couple .py files and demo notebooks
• Full scale library

Julia has something like this and @defeo mentioned it was pretty effective to encourage people to share and publish their code by making the process darn easy.

Using CookieCutter should also make it easy to support optional features (like Travis Support; see discussion on #4).

(thanks @defeo for bringing this up and @embray for suggesting CookieCutter).

This would advertise how one can write the documentation so that one can do "sage_sample?".
And it's a step toward really having all the documentation in the sources for better localitty, with just boilerplate in docs/

Currently there are a lot of commands mentioned in the documentation that the user should execute. And they are all prefixed by $ signs. This is annoying since it hinders easy copy pasting.
For example try executing this

$ mkdir mydir
$ cd mydir
$ echo "hello world" > some_file
$ cat some_file
$ cd ..
$ rm -r mydir

v.s executing this:

mkdir mydir
cd mydir
echo "hello world" > some_file
cat some_file
cd ..
rm -r mydir