Tutorial

To start with, you will need a GitHub account and an account on PyPI (optional). 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.

Step 1: Install Python Framework

$ pip install --user python-framework

Step 2: Initialize Your Package

Now it’s time to initialize your Python package.

$ shanx-py init

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: Setup Virtual Environment

$ pip install -U poetry

If you want to install prerelease versions, you can do so by passing –pre option.

$ pip install -U poetry --pre

Activate your environment.

$ cd mypackage
$ poetry shell

Here, mypackage is the name of the package that you’ll create.

Step 4: 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.

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.

$ git add .
$ git commit -m "first commit"
$ git branch -M master
$ 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 an ssh key to push the repo. You can Generate a key or Add an existing one.

Step 5: Set Up GitHub Actions

Automate, customize, and execute your software development workflows right in your repository with GitHub Actions. You can discover, create, and share actions to perform any job you’d like, including CI/CD, and combine actions in a completely customized workflow.

You only need an existing GitHub repository to create and run a GitHub Actions workflow. Your workflow configurations are stored in .github/workflows directory.

Step 6: Set Up the Docs

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.

Sphinx uses reStructuredText as its markup language and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.

We are making use of Read the Docs Sphinx Theme. This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devices. This theme is used primarily on Read the Docs but can work with any Sphinx project.

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub optionally runs the files through a build process, and publishes a website.

You can host your site on GitHub’s github.io domain or your custom domain. You can automatically host to GitHub Pages using Using GitHub Actions.

Step 7: 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, you can release your package using poetry.

See PyPI Setup for more information.

Having problems?

Visit our 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.

Note

Did you find any of these instructions confusing? Edit this file and submit a pull request with your improvements!