CreatePythonProject

Creating a New Python Project

PyKern automates the creation of a Python module or library that will be ready for use with PyPI, Read The Docs and related services.

Here are simplified instructions, which only work for RadiaSoft projects.

First, create a RadiaSoft GitHub repository with no files. I've ​used rssynergia as an example. Assuming you are in a RadiaSoft VM (or in any unix-like environment where PyKern is properly installed), do the following (or equivalent, using the name of your repository and an appropriate description):

cd ~/src/radiasoft/
git clone https://github.com/radiasoft/rsfriction
cd rsfriction
pykern projex init-rs-tree 'Python library for simulating the dynamical friction force exerted on ions by magnetized electrons'
git commit -am 'initial setup'
git push
python setup.py develop

One can also work with a non-RadiaSoft repository, but the argument "init_rs_tree" must be changed to "init_tree" and then several string arguments must be supplied.

Helpful hints can be obtained from

pykern projex -h

However, you may also want to look at the source code for projex.py.

Test PyPI

When you setup PyPI, you should start with the test site. The packages should be registered with the builder user. First click on Package submission on the left side:

Then upload the PKG-INFO file that was created by pykern setup.py develop. It's located in, e.g. ~/src/radiasoft/rssynergia/rssynergia.egg-info/PKG-INFO:

At this point testpypi is ready to go.

Travis

We use Travis for continuous integration and deployment. You login to travis-ci.org with your GitHub credentials. You'll have to authorize Travis to access GitHub. Click on My Repositories on the left side the page:

Then click on Radisoft:

You'll see a list of all the GitHub repos, turn on the repo you want:

Go to Settings by clicking on the little gear just to the left of the repo name to get to settings. Turn on Build only if .travis.yml is present and turn off Build pull requests:

On Settings, add three environment variables: PKSETUP_PYPI_IS_TEST=1, PKSETUP_PYPI_USER=****, and PKSETUP_PYPI_PASSWORD='*****'. Make sure that Display value in build log is OFF for the user and password. Here's what it should look like:

Make sure you quote the value for PKSETUP_PYPI_PASSWORD, e.g.

PKSETUP_PYPI_PASSWORD    'my password'

This is a normal bash quoting, because Travis doesn't quote automatically.

Go back to your git clone, and commit a small change to initiate the build. You'll see something like this under Builds:

If all goes well, it should turn green, and you package will be deployed on Test PyPI.

PyPI

Once you are sure the package is deploying successfully to Test PyPI, configure it to deploy to PyPI.

You'll need to register it with PyPI just as you did with Test PyPI.

Change the credentials in Travis to the PyPI credentials. Don't forget to delete PKSETUP_PYPI_IS_TEST from the Travis environment.

Kick off a build by commiting a change to the repo (master branch)

https://testpypi.python.org/pypi?%3Aaction=submit_form pykern.pksetup.pkdeploy provides full automation for PyPI, Travis, and ReadTheDocs. You start by using pykern.pkcli.projex as follows:

All the pieces are in place at this point.

ReadTheDocs

To compile the documentation on ReadTheDocs, you'll need to import the project. Go to ReadTheDocs Dashboard and click on Import a Project:

This will show you a list of repositories, click on the [+] next to the repository you want to import:

Select the Edit advanced project options and click Next:

Enter a description. Select Python Programming Language. Fill in Project homepage to GitHub repo URL. Then click Finish:

Click on Admin button and then Advanced Settings (on the left):

Check Install your project inside a virtualenv.

Set the Default Version to latest.

Check Give the virtual environment access to the global site-packages dir:

Finally, click Submit.

You may want to edit docs/index.rst with a longer description.