<!---->

PyPI Package Template Instructions

1. Choose a name that does not exist in pypi. You can check by going to https://pypi.org/simple/{myawesomenew_package}; if you recieve a 404 error the name has not been taken.
2. Replace all "mypackage" names, strings, etc. in this repo with your desired package name (e.g., "myawesomenewpackage"). The command below makes this simple; run this after cloning the repo locally.

~~~bash $ for file in $(find . -type f -not -path "./.git/*"); do sed -i "s/mypackage/myawesomenewpackage/g" $file; done ~~~

You should similarly replace all instances of "mahynski" with your GitHub username. Also, rename the my_package directory to match your chosen name.

~~~bash $ mv mypackage/ myawesomenewpackage/ $ git add myawesomenewpackage/ $ git commit -m "created myawesomenewpackage" . ~~~

1. Get coding! Follow the instructions below concerning Documentation, etc. for good coding practices. When you are ready to publish the code, proceed to step 4.
2. Bump the version appropriately in "mypackage/init_.py" and in the CITATION.cff file.
3. When finished FIRST go to Zenodo and enable preservation of this repo; THEN create a release on GitHub. Zenodo will automatically detect the new release and create a DOI and badge. Update the badge in this README.md file and in the docs/index.rst file with the new one generated by Zenodo.
4. Finally, follow these instructions to publish to PyPI.
5. Create a "dev" branch from main on which future development should occur (not main); when future releases are ready they can be merged into the main branch. This follows a gitflow management model instead of Google's "live at head" philosophy.

Best Practices

Environment

Create a conda/mamba environment then create an editable install so you can easily test and modify things during development.

~~~bash $ mamba create -n awesomeenv python=3.10 $ mamba activate awesomeenv $ cd myawesomenewpackage $ pip install -e . # Local installation $ python -m ipykernel install --user --name=awesomeenv # Install kernel $ jupyter notebook --port 4321 --ip='*' --NotebookApp.token='' --NotebookApp.password='' # Launch jupyter server ~~~

Documentation

Documentation is stored in the docs/ folder and is currently set up to use sphinx.

First create the requirements.txt that will be needed to build the documentation. This is done by running pip-compile on the requirements.in file.

Be sure to add any additional requirements you add to the pyproject.toml file etc. to requirements.in also.

~~~bash $ cd docs $ pip install Sphinx $ pip install pip-tools $ pip-compile requirements.in # Modify as needed before executing ~~~

Adjust the docs/conf.py as desired. Then run docs/make_docs.sh to setup the documentation initially. You can manually add and adjust later.

~~~bash $ bash make_docs.sh ~~~

This command creates documentation for your package, but you still need to adjust the main landing page (docs/index.rst) manually. Here is a primer on reStructured text markup language.

Go to https://about.readthedocs.com/ to link your repo to build and host the documentation automatically! The .readthedocs.yml file contains the configuration for this which you can adjust as needed.

Alternatively, you can start the documentation setup fresh using sphinx-quickstart in the docs/ directory:

~~~bash $ sphinx-quickstart ~~~

Unittests

Build unittests in the tests/ directory. The pyproject.toml automatically configures pytest to look in tests/. The following will run all unittests in this directory.

~~~bash $ python -m pytest ~~~

The GitHub workflow in .github/workflows/python-app.yml will also run these tests and perform coverage checks using this command. This workflow is triggered automatically on the main branch, but you can adjust this file so this is automatically triggered on others as well.

Code coverage is configured to work with codecov.io; visit their website to enable this for your new project. Add your codecov repository token (CODECOV_TOKEN) to this repo as an "Actions" secret. Then update the badge (click on the repo on codecov.io and navigate to Configuration > Badges & Graphs) in this README.md file and in the docs/index.rst file.

Linting

Automatic code linting is provided via pre-commit; refer to the .pre-commit-config.yaml file for the specific configuration which you can adjust as needed.

Run pre-commit to lint new code, then commit the changes.

~~~bash $ pre-commit run --all-files ~~~

Typing

While optional, it is best to include typing in your code - see mypy.

~~~bash $ mypy --ignore-missing-imports mynewfile.py ~~~

Demo

Consider building a streamlit demo to illustrate the capabilities of the tool. This can be hosted for free in the community cloud. Refer to their documentation for easy setup, which allows you to put your app.py file right here in a public repo, e.g., streamlit/app.py. You may also consider using a HuggingFace space instead.

Logo

You can generate a logo or other art using Google Gemini or other AI tools. Note that "the Chicago Manual of Style's website recommends you cite AI-generated images like any other image, while including both the name of the AI tool that generated the image, the company that created the AI, and the prompt that generated the image." Modify the html_logo tag in the docs/conf.py to point to the logo.

The logo for this repository (docs/_static/logo.png) was generated using Google Gemini (Imagen 3) on Nov. 28, 2024 with the prompt "Make a logo inspired by code as a template for python projects."

Citation

Update the CITATION.cff, CODEOWNERS, and pyproject.toml files to include all code authors and maintainers appropriately.