Usage¶
Welcome to the ultimate Python project template. The goal of this usage page is to show you how to update this template for your needs.
Step 0: Setup Your Environment¶
Environment handling is a huge pain in Python. Hopefully,
you’re using an IDE that handles it for you. Regardless,
to ensure everything works locally on your machine,
you’ll want to kick things off by installing all of
the modules in the requirements.txt file in the
root directory. One way to do this is as follows:
pip install -r requirements.txt
Then, just to make sure everything works, you can try to run the following commands:
py setup.py build_sphinx
This command will generate all of the documentation for the repo locally.
py -m pytest
This command will test all of the code in the repo.
Step 1: TODO or not TODO¶
Once your environment is setup,
you’re going to want to address all of the TODO
messages around the repo. I recommend starting with
the setup.py file in the root directory. There,
you can specify the name of your project, among other
things such as your name and email address.
Once you’ve updated the setup.py file, make your
way over to conf.py file in the docs directory.
There you’ll find a handful of fields to update as well.
That should take care of all the TODOs!
Step 2: File/Folder Renaming¶
With the TODOs out of the way, the next step is to rename the appropriate files and folders. For example, you’ll want to rename the package folder to the name of your project. Be sure to do this using a refactor tool of your favorite IDE. Otherwise, you’ll have to chase references to the old name all around the repo.
Once you’ve renamed the package folder, go ahead and rename the module file to whatever you like. It’s fine to give it the same name as the package folder.
Finally, you’ll want to update these names in the
documentation. As a result, head over to the docs
directory and rename the package.rst file to
the name of your project. Inside this file, make
sure automodule has the right package and module
names. Then, head to index.rst and change
the name of the package reference under the table
of contents.
Step 3: Create All Necessary Accounts¶
Many of the features of this template rely on third-party services. For example, the documentation is automatically generated by Read the Docs. However, to get the docs to render, you’ll need to create an account. Similarly, you cannot publish this package without signing up for PyPI, the Python package index.
Step 4: Loose Ends¶
Once you have the accounts you need, there are a couple loose ends to tie up.
First, head over to the GitHub workflows
directory and check out the deploy.yml file. There you
will see a TODO for the secret key for PyPI. You’ll want to
generate an API key on PyPI and save it to GitHub under the
name PYPI_API_TOKEN.
Second, in the same folder, check out the test.yml file.
This file is already setup to automatically test all of your
code (assuming you have tests). However, one thing you’ll
want to do is specify the list of Python versions that you
want to support. If you’re not sure, leave it as-is.
Step 5: Next Steps¶
By this point, the template should be good to go. Once you’ve
added your code, you can publish everything by creating a
release on GitHub. Before you do that, however, don’t forget
to update the version number in your setup.py file.