Package: sage-sample
This package is designed as a simpleSageMathpackage
example to serve as a good practice reference for package developers. We follow
python recommendations and adapt them to the SageMath community. You can find more
advanced documentation on python package creation onHow To Package Your Python Code.This is still a work in progress. Once this example will have
stabilized, the plan is to make acookie cuttertemplate out of it.InstallationTry thedemoon binderLocal install from sourceDownload the source from the git repository:$ git clone https://github.com/sagemath/sage_sample.gitChange to the root directory and run:$ sage -pip install --upgrade --no-index -v .For convenience this package contains amakefilewith this
and other often used commands. Should you wish too, you can use the
shorthand:$ make installInstall from PyPIsage_sample is distributed on PyPI. You can install it with the command:$ sage -pip install sage_sampleTo distribute your own package on PyPI, you will need an account on pypi.org
(maybe at first on test.pypi.org)You also need to install setuptools, wheel and twine:$ sage -pip install –upgrade setuptools wheel twineMake the package:$ python setup.py sdist bdist_wheelUpload and test the package to the test PyPI repository:$ twine upload –repository-urlhttps://test.pypi.org/legacy/dist/*
$ sage -pip install -ihttps://test.pypi.org/simplesage_sampleAnd later, upload your distribution to the real PyPI [optionally sign it with GPG]:$ twine upload [-s] dist/*UsageOnce the package is installed, you can use it in Sage with:sage: from sage_sample import answer_to_ultimate_question
sage: answer_to_ultimate_question()
42See also thedemo notebook.SetupAll packaging setup is done throughsetup.py. To create your own package
follow the strcuture of the file and change the parameters accordingly.Source codeAll source code is stored in the foldersage_sampleusing the same name as the
package. This is not mandatory but highly recommended for clarity. All source folder
must contain a__init__.pyfile with needed includes.TestsThis package is configured for tests written in the documentation
strings, also known asdoctests. For examples, see thissource file. See alsoSageMath’s coding conventions and best practices document.
With additional configuration, it would be possible to include unit
tests as well.Once the package is installed, one can use the SageMath test system
configured insetup.pyto run the tests:$ sage setup.py testThis is just callingsage-twith appropriate flags.Shorthand:$ make testDocumentationThe documentation of the package can be generated using Sage’sSphinxinstallation:$ cd docs
$ sage -sh -c "make html"Shorthand:$ make docFor this to work on your own package, make sure you follow the same
structure as we do here:Create adocsfolder containing the exact sameMakefileand asourcefolder.Copy and paste thedocs/source/conf.pyfile from this package and update
the few project specific variables at the beginning of the file.Create anindex.rstfile as well as a<modulename>.rstfile for each
module you want on the documentation.Travis CI integrationScripts that runmake teston various SageMath versions on the
Travis CI system are included.https://docs.travis-ci.com/user/for-beginnersexplains how to enable
automatic Travis CI builds for your GitHub-hosted project.The scripts download and install binary releases (7.1-7.4) from a
SageMath mirror.  Edit.travis-install.shif some optional or
experimental SageMath packages need to be installed prior to running
your package.  Edit.travis.ymlto change the list of SageMath
versions used.Automatically deploying documentation to GitHub pages using Travis CIFirst do the steps described above to enable Travis CI integration
of your GitHub-hosted project.If you don’t already have GitHub pages for your project: Create and
checkout a branchgh-pagesin your repository and put an empty
file.nojekyllin it (seehttps://help.github.com/articles/files-that-start-with-an-underscore-are-missing/).
Then commit it and push it to GitHub:$ git clone --single-branch --depth 1 https://github.com/USER/PROJECT.git gh-pages
$ cd gh-pages
$ git checkout --orphan gh-pages
$ git rm -rf .
$ touch .nojekyll
$ git add .nojekyll
$ git commit -m "Initial commit"
$ git push -u origin gh-pages
$ cd ..(Back in your working copy:) Generate a new ssh key pair with an
empty passphrase:$ ssh-keygen -t dsa -f .travis_ci_gh_pages_deploy_keyAdd the public ssh key (contents of the file.travis_ci_gh_pages_deploy_key.pub) to your GitHub repository
as a deploy key (Settings/Deploy keys/Add deploy key).
Title: Key for deploying documentation to GitHub pages.
Check Allow write access.Install the Travis CI command-line client fromhttps://github.com/travis-ci/travis.rb:$ gem install travisLog in to Travis CI using your GitHub credentials:$ travis loginEncrypt the private ssh key, add the decryption keys
as secure environment variables to Travis CI, and
add code to.travis.ymlto decrypt it:$ travis encrypt-file .travis_ci_gh_pages_deploy_key --add before_scriptAdd the encrypted private ssh key to the repository:$ git add .travis_ci_gh_pages_deploy_key.encHave git ignore the other keys (and the gh-pages directory):$ echo >> .gitignore
$ echo "/.travis_ci_gh_pages_deploy_key" >> .gitignore
$ echo "/.travis_ci_gh_pages_deploy_key.pub" >> .gitignore
$ echo "/gh-pages" >> .gitignore
$ git add .gitignoreOptionally, edit.travis.ymlto adjust variablesDEPLOY_DOC_...Commit all changes to GitHub.  The Travis CI build should then run
automatically and deploy it:$ git add .travis.yml
$ git commit -m "Deploy built documentation to GitHub"
$ git pushThe deployed documentation will be available at:https://USER.github.io/PROJECT/This can be customized by changingDEPLOY_DOC_TO_DIRECTORY=/to another directory in.travis.ymlFor example, settingDEPLOY_DOC_TO_DIRECTORY=doc/htmlwill make
the deployed documentation available at:https://USER.github.io/PROJECT/doc/html/