Turn this package template into a cookie for CookieCutter

[nthiery]

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 https://github.com/nthiery/sage_sample/pull/4).

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

[nthiery]

Strategy note: At this stage we are still in the preliminary phase of exploring which features we want in a Sage project and how to best implement them. Agile development seems easier on a sample package than on a package template. So I would suggest that, for now, we focus on further enhancing sage_sample, throwing directly in every generaly useful feature we may think of. And then, once things will have stabilized, to make a cookie cutter out of it with a combination of standard and optional features.

What do you think?

[koffie]

Just to mention that @mmasdeu recently made a cookie cutter template. After using that to make my repository MD sage into a pip installable python package, I started thinking about it. And there is one thing that I don't like about the CookieCutter setup, namely it looks to me the CookieCutter thing is something you do once before start your project, but it is very difficult to later use git to then get improvements to the CookieCutter and merge into your own package. While forking the sage_sample repository makes that relatively easy.

Let new_project be the name of a repository made with CookieCutter. For this I think the CookieCutter should initialise the git repo of new_project in the following way:

1) Make a branch called sage_sample in new_project and make this match master branch of sage_sample, or maybe even better a tagged commit on the master branch in order to stay reproducible. 2) Make a branch called master in new_project an apply all the project specific changes to this branch.

This way, if sage_sample gets improvements, then people can do the following on new_project in order to get the latest improvements to the sage_sample project:

git checkout sage_sample
git pull sage_sample master #get the recent version of https://github.com/sagemath/sage_sample
git checkout master
git merge sage_sample #merge the most recent changes of sage sample in to new_project.

[nthiery]

Just to mention that [1]@mmasdeu recently made a [2]cookie cutter template.

Yes! I was really glad to see someone work in that direction. Thank you @mmasdeu! Sorry I did not get time to provide feedback on sage-devel.

After using that to make my repository [3]MD sage into a pip installable python package, I started thinking about it. And there is one thing that I don't like about the CookieCutter setup, namely it looks to me the CookieCutter thing is something you do once before start your project, but it is very difficult to later use git to then get improvements to the CookieCutter and merge into your own package. While forking the [4]sage_sample repository makes that relatively easy.

Indeed: the CookieCutter paradigm is great for setting up initial boilerplate, but not for evolving it. Hopefully, once sage_sample will have stabilized, the typical boilerplate for a Sage package won't need to evolve too much. That especially for trivial or simple packages which I see as target #1 of a CookieCutter: we can expect authors of larger packages to be able to handle some more complexity, e.g. with approaches as you suggest.

That being said: intrinsically the issue is not so much the CookieCutter approach, but the amount of boilerplate needed to write a package, and its duplication across packages. So the more of that boilerplate we can factor out, the less there remains to evolve. Which is my motivation for initiating sage_package: if someone finds a way to improve it (e.g. the Sphinx configuration), then all packages using it immediately benefit from it.

In a perfect world, the boilerplate would be reduced to metadata, typically all concentrated in the setup.py. I don't know however if there would be an easy way to factor out boilerplate like travis configuration.

@koffie: if at some point you find the time to summarize in the READMEs some of the things we are discussing here -- in particular about the development workflow for sage_sample -- that would be great.

Cheers,

[koffie]

Yes I do plan to improve the documentation as well. I am starting to notice that this package has a dual functionality:

1. Be a good starting point for development of other packages
2. Document how to develop an external sage package

In order to cater for this dual need I think it also makes sense to split up te documentation of this package into two parts.

1. The documentation currently in docs/ this should be for the documentation of the actual package, build with sphinx and automodule from .py files.
2. New documentation in dev-docs/ this should contain most of the documentation currently in README.rst and be written in plain rst files (possibly build with sphinx) where we document development best practices.

In this way we can now rewrite README.rst in such a way that it won't need heavy modification once someone forks the project for an actual package. We would of course include links to both documentations in the README.rst

If people have strong feeling about a different directory layout for the two documentations then this is also OK.

[nthiery]

On Wed, Sep 06, 2017 at 10:06:49AM +0000, Maarten Derickx wrote:

Yes I do plan to improve the documentation as well.

Great, thanks!

I am starting to notice that this package has a dual functionality:

1. Be a good starting point for development of other packages

2. Document how to develop an external sage package

   In order to cater for this dual need I think it also makes sense to split up te documentation of this package into two parts.

3. The documentation currently in docs/ this should be for the documentation of the actual package, build with sphinx and automodule from .py files.
4. New documentation in dev-docs/ this should contain most of the documentation currently in README.rst and be written in plain rst files (possibly build with sphinx) where we document development best practices.

Good point. It might be better to actually separate the two, like Python does with:

    1. https://github.com/pypa/sampleproject
    2. https://packaging.python.org/

One piece of rationale is that there may be several ways to share code, starting from shipping a single py files in the simplest cases.

A starting point for 2. could be:

    https://wiki.sagemath.org/CodeSharingWorkflow

(I mean in term of content; we may want to host the doc elsewhere than the wiki; it could also be in the developers guide, or in a separate github-hosted project like the Python people do)