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

README.rst

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.

Initialitzation

Prerequisites

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)

Usage

  1. Shape your package:

    $ cookiecutter https://github.com/mmasdeu/sage_package_template
    

    (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 https://pypi.python.org/pypi

    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 setup.py 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 __init__.py file with the needed includes.

Tests

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 setup.py to run the tests:

$ sage setup.py test

This is just calling sage -t with appropriate flags.

Shorthand:

$ make test

Documentation

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

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

Shorthand:

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