Skip to content
A cookiecutter for SageMath projects
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


A Cookiecutter for SageMath projects

This Cookiecutter generates the basic structure to develop your own SageMath package, and includes the possibility of authomaticaly creating a GitHub repository and configurating it together with Travis CI for automatic testing and documentation deployment. We follow python recommendations and adapt them to the SageMath community. You can find more advanced documentation on python package creation on How To Package Your Python Code.



For a smooth setup process you will need:

  • a GitHub account,

  • to have already linked Travis CI to your GitHub account, by logging in once on the website,

  • to have git and the python packages cookiecutter and sagemath.

    To install cookiecutter run:

    $ pip install cookiecutter

    (add --user if you don't have enough privileges)

    To install sagemath run:

    $ sage -pip install --upgrade sagemath

    (add --user if you don't have enough privileges)


  1. Shape your package:

    $ cookiecutter

    (the cookiecutter binary may have been installed somewhere outside of your PATH, so you might need to find or locate it)

  2. Follow the instructions that come up on the terminal.

    First you will be asked to define a set of variables that will inicialize your project:

    • full_name: the author(s) of the package.
    • email: the email adress(es) of the author.
    • github_username: The account on which to place the GitHub repository.
    • project_name: The full name of the package. It will appear mainly on the documentation.
    • app_name: The name (slug) of the package. It will be used to install and import the module.
    • project_short_description: A short sentence to describe what the package does. Also, the short description on the GitHub repository.
    • project_version: Initial version number.
    • travis_ubuntu_version: The version of Ubuntu that you set Travis CI to use (for automatically running tests).
    • sage_required_version: Minimum SageMath version needed for the package.
    • sage_mirror: When doctesting with Travis CI, the mirror from which to download the SageMath binaries.
    • keywords: Keywords for the both the GitHub repository and the Python repository PyPI.
    • Select open_source_license: License of distribution of the package. For more information see Licenses&Standards.

    Next, you will be asked to answer a series of questions in order to configure (or not) GitHub and Travis CI. For more information on the setup process check the MANUAL_INSTALL.rst file inside your newly created package.

  3. Now your package is shaped and ready! Read the Developer's guide (next section) to see how to use and modify your newly created package.

  4. Deploy the package to PyPI (optional).

    Create an account at

    Install twine:

    $ pip install --upgrade twine

    Create the distribution (you can also use bdist instead to create a built distribution instead of a source one):

    $ sage -python sdist

    Upload to PyPI:

    $ twine upload dist/* -r pypi

Developer's guide

Source code

All source code is stored in the folder using the same name as the package. This is not mandatory but highly recommended for clarity. All source folders must contain a file with the needed includes.


This package is configured for tests written in the documentation strings, also known as doctests. See SageMath'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 in to run the tests:

$ sage test

This is just calling sage -t with appropriate flags.


$ make test


The documentation of the package can be generated using Sage's Sphinx installation:

$ cd docs
$ sage -sh -c "make html"


$ make doc
You can’t perform that action at this time.