to emphasize it is also meant for use by non-eScience projects.

To promote the RSD, we could add a link to in in the generated README.

https://github.com/research-software-directory/research-software-directory/issues/new/choose

https://github.com/research-software-directory/research-software-directory/tree/master/.github

For most of the badges, putting in the user's slug is going to be correct or at least a much better approximation of the correct value than having cff-converter-python in there. That's exactly why we're using cookiecutter!

Or use a single source for the version number

Thanks @jspaaks for the suggestion!

Sphinx can be configured to use markdown for documentation instead of (or in addition to) .rst. I always find it a bit schizophrenic to have a README.md and then use .rst for the documentation. Also, markdown is easier to use (I guess this depends on what you are used to).

So, what do we recommend?

I really like PyTest, and the guide says it's preferred over plain unittest and nose. Do we all agree on that? If so, I can submit a pull request for a port of the example test case to PyTest.

The template should ask whether the user wants Python 2 and Python 3 support (both should be possible). As more libraries are dropping Python 2 support (e.g., pylint), requirements, etc. should be adapted based on Python version.

GitHub recommends using the https url for cloning. So instead of:

https://github.com/NLeSC/python-template/blame/a34b25535bd9b98d52fc581ce393fd1a6bbecb76/%7B%7Bcookiecutter.project_slug%7D%7D/README.rst#L140

git clone [email protected]:{{ cookiecutter.github_organization }}/{{ cookiecutter.project_slug }}.git

we should do

git clone https://github.com/{{ cookiecutter.github_organization }}/{{ cookiecutter.project_slug }}.git

I can't say I really understand/remember the reason, but if I use the first option, I always get a "Permission denied (publickey)." error.

The generated repository contains a tests/test_lint.py file which calls a linter. A nicer solution that was probably not available when this was first made is to use the PyTest plugins pytest-codestyle and pytest-docstyle. Note that the main directory must be added to the testpaths in setup.cfg for them to check the source of the program, rather than only the tests.

@vincentvanhees can you make @benvanwerkhoven and me admins of this repository?

Many thanks!

We could change the text of the README to something like

Install cookiecutter in user space (make sure that ~/.local/bin is on the path)

pip3 install --user cookiecutter

Not sure it should say pip or pip3, on my Ubuntu based system I still get Python2 if I do pip...

I would then put it as the first step.

Do we recommend using tox for locally running tests with multiple versions of Python?

(If so, this should also be added to the guide)

The empty nlesc Python project could have a better name.

Ideas:

• nlesc-python

Suggestions are welcome!

Fix: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html

The generated Python files contain an encoding tag which sets the source encoding to UTF-8. In Python 2, this is useful, as the default is 7-bit ASCII, but in Python 3 the default is already UTF-8, so the tags are superfluous. And since Python 2 is deprecated, they can be removed.

To specify which dependencies your package has install_requires=['mydep'] in setup.py should be used.

Now the setup.py does not contain that key, making it hard to find how to specify package dependencies.

It is possible to test python code in travis, on a Windows environment, using chocolately. Would this be a useful feature for the template?

Using GitHub action

• to test package generation using the instructions in README
• test the generated package

We have mypy configuration in setup.cfg, but mypy isn't run automatically. There's a mypy plug-in for pytest that runs mypy automatically as part of the test suite.

I like it, but I guess there are quite a few people who don't use type annotations yet. Then again, they can always remove it. So should the default be to run mypy as part of the tests, using pytest-mypy?

The supplied docs/conf.py gives a whole bunch of errors if you run prospector. Having it ignore the docs/ directory is probably a good idea.

The guide specifies three code quality/coverage tools: codacy, Scrutinizer, and Landscape, but does not make a recommendation.

Do we recommend one? If so, which one? I have only used codacy, so I can't really recommend anything else...

Some files were added to the project, so it is a good idea to redo the directory tree.

Having the project setup information in the readme results in a really cluttered readme. It is probably better to put this information in a separate document.

Added the following items to .gitignore file:

• coverage.xml
• docs/apidocs (doc/apidoc is already ignored, but shpinx is configured to write to docs/apidocs)
• IDE config files

This will reduce accidental git adds.

To show impact of the template, it would be nice if we could link to external software for which the template was used. Maybe we can stimulate external users to report usage and/or have an automated process that does this.

https://stackoverflow.com/questions/48108328/cookiecutter-template-testing-what-is-cookies-bake

The documentation configuration (conf.py) generated with newer versions of Sphinx is much cleaner. So maybe it is a good idea to clean or regenerate this file.

The current set-up has the development tools listed in setup.py, and has you install them via python setup.py .[dev]. This command does two things: it installs your package and its dependencies into your local environment, and it installs the development tools into your local environment.

Next, if you run python setup.py test, setuptools will create a separate environment, install your package in it and any dependencies that aren't already in your local environment, and then run your tests. They pass, you push, and your CI fails, because it runs python setup.py test in a clean environment (not having done python setup.py .[dev] some time ago) and so ends up with a newer version of a library that breaks your code. Locally, it works because it's using the stale dependency that was installed when you installed the development tools.

So I don't like having my package and especially its dependencies installed in my working environment, because it makes my environment less similar to the one on the CI. But the way things are now set up, I can't have that unless I either manually install the development tools, or install them using setup.py and then manually uninstall my own package.

So I'd propose using a requirements-dev.txt instead with a list of development tools, so that you can pip install -r requirements-dev.txt them. But this stuff is complicated, and I'm probably missing some considerations. Comments welcome :-).

For example, prospector, yapf, isort.

My current preference would be to not have them in the requirements, because 'normal' users won't use them (however, the same could be said about testing packages).

I found the following error while trying to create a new project:

Error message: 'matrix' is undefined

Here is the full output:

project_name [My Python Project]:  
project_slug [my_python_project]: 
project_short_description []: 
version [0.1.0]: 
github_organization []: 
Select open_source_license:
1 - Apache Software License 2.0
2 - MIT license
3 - BSD license
4 - ISC license
5 - GNU General Public License v3 or later
6 - Not open source
Choose from 1, 2, 3, 4, 5, 6 [1]: 
Select apidoc:
1 - no
2 - yes
Choose from 1, 2 [1]: 
pypi_user [no_pypi_travis_deployment]: 
full_name [John Smith]: 
email [[email protected]]: 
copyright_holder []: 
code_of_conduct_email [[email protected]]: 
Unable to create file '.github/workflows/build.yml'
Error message: 'matrix' is undefined
Context: {
    "cookiecutter": {
        "_template": "https://github.com/nlesc/python-template.git",
        "apidoc": "no",
        "code_of_conduct_email": "[email protected]",
        "copyright_holder": "",
        "email": "[email protected]",
        "full_name": "John Smith",
        "github_organization": "",
        "open_source_license": "Apache Software License 2.0",
        "project_name": "My Python Project",
        "project_short_description": "",
        "project_slug": "my_python_project",
        "pypi_user": "no_pypi_travis_deployment",
        "version": "0.1.0"
    }
}

Is it a good idea to add a basic example of how to setup logging?

They should probably go in the generated readme, under project setup.

pip install cffconvert
cffconvert --validate
cffconvert --outfile .zenodo.json -ig --outputformat zenodo
cffconvert --outfile codemeta.json -ig --outputformat codemeta

I used the template to create a package and ended up with the line

description=""bla"",

which is not valid Python.

The Sphinx configuration uses the alabaster theme, which IMHO is not so nice as the readthedocs theme. Should we switch the default?

Nice option to add: https://docs.travis-ci.com/user/deployment/pypi/

Deployment can be configured on separate stages for test and deploy.

Link to fair-software.nl and to github repo in nlesc/template.
See NLeSC/boatswain#14 or https://github.com/DeepRank/PSSMGen for example.

The badge table added in ce95843#diff-9d30df65be9fca50822c17e77ab06613 uses urls for already existing libraries. This will cause confusion as badges might be green for the other library, but red for the repo which contains the README with the badges. The cookiecutter should use template variables.

We recommend using rst for documentation, but provide no formatting rules in .editorconfig.

For an example see https://github.com/citation-file-format/doi2cff

If you have a dash in your repository name (e.g. 'python-template' :)), then the Python package will also have a dash in its name, which is invalid Python. Is there any way of converting dashes to underscores here?

Having a conftest.py (even an empty one) in your top code directory makes PyTest add that path to the PYTHONPATH, so that you can import your code from your test cases using absolute imports. I took me a long time to figure that out (and Ben's template, which I was using before, used a hack instead). It would be nice to have such a file in here, ideally with a comment explaining why it's there.

(I'll submit a pull request if you think it's a good idea.)

See for example https://github.com/NLESC-JCER/cpp2wasm.

As described in https://packaging.python.org/tutorials/managing-dependencies/ the Python Foundation is advocating the use of pipenv.

We could also advocate the use of pipenv.

This can be done by implementing the advice on https://realpython.com/pipenv-guide/ into this template.

Change sentence: The generated README contains extensive documentation about the project setup and provides further instructions on what to do.

Two of the 3 example tests fail to run with an error message:

fixture 'my_project' not found

and there is an unused fixture deffined. Also the example test class inherits from object which is considered bad style in python 3.

Should new projects be created with a CITATION.cff file?

Configure sphinx to allow google documentation style. See https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/ for an example.