Tutorial ======== .. note:: Did you find any of these instructions confusing? `Edit this file`_ and submit a pull request with your improvements! .. _`Edit this file`: https://github.com/elgertam/cookiecutter-pipenv/blob/master/docs/tutorial.rst To start with, you will need a `GitHub account`_ and an account on `PyPI`_. Create these before you get started on this tutorial. If you are new to Git and GitHub, you should probably spend a few minutes on some of the tutorials at the top of the page at `GitHub Help`_. .. _`GitHub account`: https://github.com/ .. _`PyPI`: https://pypi.org/ .. _`GitHub Help`: https://help.github.com/ Step 0: Install pipsi (Recommended) ----------------------------------- Pipsi_ is `Armin Ronacher's`_ "pip script installer"; it installs Python scripts into their own virtualenvs that pipsi itself manages. Pipsi is useful for tools like Ansible, Pygments or Cookiecutter that run as first-class executables on your system. .. code-block:: bash $ curl https://raw.githubusercontent.com/mitsuhiko/pipsi/master/get-pipsi.py | python When initially installing pipsi, I ran into some Python 3 compatibility issues, and so created my own installer. .. code-block:: bash $ curl https://gist.githubusercontent.com/elgertam/2d50ea280d2395dd2bbedbb169c59d2e/raw/0bba09f4ced1d702654fe51d5db75133a34749ef/install_pipsi.sh | bash .. _`Armin Ronacher's`: http://lucumr.pocoo.org/ Step 1: Install Cookiecutter and Pipenv --------------------------------------- Assuming you installed Pipsi without an issue, install Cookiecutter and Pipenv. .. code-block:: bash $ pipsi install cookiecutter $ pipsi install pipenv If you were not able to install pipsi in step 0, install Cookiecutter to your global site-packages or a virtualenv. We'll use the latter. If you are stuck using Python 2, be sure to first ``pip install -U virtualenv`` and then use ``virtualenv`` in place of ``python -m venv``. .. code-block:: bash $ mkdir -p ~/.local/venvs/ $ python -m venv ~/.local/venvs/cookiecutter Activate the virtualenv and install cookiecutter. .. code-block:: bash $ source ~/.local/venvs/cookiecutter/bin/activate $ pip install -U cookiecutter Now you can use Cookiecutter from ``~/.local/venvs/cookiecutter/bin/cookiecutter``. .. code-block:: bash $ ~/.local/venvs/cookiecutter/bin/cookiecutter --version Cookiecutter 1.6.0 from /home/user/.local/venvs/cookiecutter-test/lib/python3.6/site-packages (Python 3.6) Follow similar steps for Pipenv. .. code-block:: bash $ mkdir -p ~/.local/venvs/ $ python -m venv ~/.local/venvs/pipenv $ source ~/.local/venvs/pipenv/bin/activate $ pip install -U pipenv ... $ ~/.local/venvs/pipenv/bin/pipenv--version pipenv, version 11.10.0 On Windows, activate it like this. You may find that using a Command Prompt window works better than gitbash/mingw64 bash. .. code-block:: powershell > \path\to\env\Scripts\activate Step 2: Generate Your Package ----------------------------- Now it's time to generate your Python package. Use cookiecutter, pointing it at the cookiecutter-pypackage repo: .. code-block:: bash $ cookiecutter https://github.com/elgertam/cookiecutter-pipenv.git You'll be asked to enter a bunch of values to set the package up. If you don't know what to enter, stick with the defaults. Step 3: Create a GitHub Repo ---------------------------- Go to your GitHub account and create a new repo named ``mypackage``, where ``mypackage`` matches the ``[project_slug]`` from your answers to running cookiecutter. This is so that Travis CI and pyup.io can find it when we get to Step 5. ``If your virtualenv folder is within your project folder, be sure to add the virtualenv folder name to your .gitignore file.`` You will find one folder named after the ``[project_slug]``. Move into this folder, and then setup git to use your GitHub repo and upload the code: .. code-block:: bash $ cd mypackage $ git init . $ git add . $ git commit -m "Initial skeleton." $ git remote add origin git@github.com:myusername/mypackage.git $ git push -u origin master Where ``myusername`` and ``mypackage`` are adjusted for your username and package name. You'll need a ssh key to push the repo. You can `Generate`_ a key or `Add`_ an existing one. .. _`Generate`: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/ .. _`Add`: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/ Step 4: Install Dev Requirements -------------------------------- You should still be in the folder containing the ``Pipfile`` file. .. code-block:: bash $ pipenv install --dev Step 5: Set Up Travis CI ------------------------ `Travis CI org`_ [*]_ is a continuous integration tool used to prevent integration problems. Every commit to the master branch will trigger automated builds of the application. Login using your Github credentials. It may take a few minutes for Travis CI to load up a list of all your GitHub repos. They will be listed with boxes to the left of the repo name, where the boxes have an ``X`` in them, meaning it is not connected to Travis CI. Add the public repo to your Travis CI account by clicking the ``X`` to switch it "on" in the box next to the ``mypackage`` repo. Do not try to follow the other instructions, that will be taken care of next. In your terminal, your virtualenv should still be activated. If it isn't, activate it now. Run the Travis CLI tool to do your Travis CI setup: .. code-block:: bash $ travis encrypt --add deploy.password This will: * Encrypt your PyPI password in your Travis config. * Activate automated deployment on PyPI when you push a new tag to master branch. See :ref:`travis-pypi-setup` for more information. .. [*] For private projects go to `Travis CI com`_ .. _`Travis CI org`: https://travis-ci.org/ .. _`Travis CI com`: https://travis-ci.com/ Step 6: Set Up ReadTheDocs -------------------------- `ReadTheDocs`_ hosts documentation for the open source community. Think of it as Continuous Documentation. Log into your account at `ReadTheDocs`_ . If you don't have one, create one and log into it. If you are not at your dashboard, choose the pull-down next to your username in the upper right, and select "My Projects". Choose the button to Import the repository and follow the directions. In your GitHub repo, select Settings > Webhooks & Services, turn on the ReadTheDocs service hook. Now your documentation will get rebuilt when you make documentation changes to your package. .. _`ReadTheDocs`: https://readthedocs.org/ Step 7: Set Up pyup.io ---------------------- `pyup.io`_ is a service that helps you to keep your requirements files up to date. It sends you automated pull requests whenever there's a new release for one of your dependencies. To use it, create a new account at `pyup.io`_ or log into your existing account. Click on the green ``Add Repo`` button in the top left corner and select the repo you created in Step 3. A popup will ask you whether you want to pin your dependencies. Click on ``Pin`` to add the repo. Once your repo is set up correctly, the pyup.io badge will show your current update status. .. _`pyup.io`: https://pyup.io/ Step 8: Release on PyPI ----------------------- The Python Package Index or `PyPI`_ is the official third-party software repository for the Python programming language. Python developers intend it to be a comprehensive catalog of all open source Python packages. When you are ready, release your package the standard Python way. (Hint: if you'd like to add documentation for this to the tutorial, I'd welcome a PR.) See `PyPI Help`_ for more information about submitting a package. Here's a release checklist you can use: https://gist.github.com/audreyr/5990987 .. _`PyPI`: https://pypi.org/ .. _`PyPI Help`: http://peterdowns.com/posts/first-time-with-pypi.html Having problems? ---------------- Visit our :ref:`troubleshooting` page for help. If that doesn't help, go to our `Issues`_ page and create a new Issue. Be sure to give as much information as possible. .. _`Issues`: https://github.com/elgertam/cookiecutter-pipenv/issues .. _Pipsi: https://github.com/mitsuhiko/pipsi