diff --git a/README.md b/README.md index 3b782e8..ffe6072 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# pyOpenSci Package Template +# pyOpenSci Python Package Template [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-) @@ -7,24 +7,25 @@ > A Python package template that supports the pyOpenSci > pure [Python packaging tutorial](https://www.pyopensci.org/python-package-guide/tutorials/intro.html). - This template can be used with [copier](https://copier.readthedocs.io) to initialize a new Python package project structure following the practices outlined in the pyOpenSci tutorial. -## Getting Started +## Get started To use this template: 1. Install copier using [pipx](https://pipx.pypa.io/stable/) or pip preferably with a [virtual environment](https://www.pyopensci.org/python-package-guide/CONTRIBUTING.html#create-a-virtual-environment). - ```sh + Global Installation: + + ```console pipx install copier ``` - or + or Environment specific installation: - ```sh + ```console pip install copier ``` @@ -33,18 +34,87 @@ To use this template: directory, even if it already exists!** That includes your current directory if that is your target. - ```sh - copier copy gh:pyopensci/pyos-package-template + ```console + copier copy gh:pyopensci/pyos-package-template path/here + ``` + + The command below will create the package directory in your current working directory. + ```console + copier copy gh:pyopensci/pyos-package-template . ``` - - Where `` could be your current directory `.` or some other path. Used in the above way, copier will use the latest tagged release, which is probably the safest option. You can provide an option `--vcs-ref` to choose specific branches as your source. You can read more about generating your project in the [copier documentation](https://copier.readthedocs.io/en/stable/generating/). -### Staying Up-to-date + +## Run the template workflow + +Once you have installed copier, you are ready to create your Python package template. +First, run the command below from your favorite shell. Note that this is copying our template from GitHub so it +will require internet access to run properly. + +The command below will create the package directory in your current working directory. + +`copier copy gh:pyopensci/pyos-package-template .` + +If you wish to create the package directory in another directory you can specify it like this: + +`copier copy gh:pyopensci/pyos-package-template dirname-here` + +## Template overview +The copier template will ask you a series of questions which you can respond to. The questions will +help you customize the template. + +Below is what the template workflow will look like when you run it. In the example below, you +"fully customize" the template. + + +```console +➜ copier copy gh:pyopensci/pyos-package-template . +🎤 Who is the copyright holder, for example, yourself or your organization? Used in the license + pyos +🎤 Who is the author of the package to be? Used in the package description. + pyos +🎤 The author's email address. Used in the package description. + youremail@youremail.com +🎤 What is the name of the project? Used as the title in the README.md and other places. + mypkg +🎤 Please provide a short description for the package. + (Finish with 'Alt+Enter' or 'Esc then Enter') +> description here +🎤 Do you want to skip all remaining questions and simply use the provided default values? + No, I want to fully customize the template. +🎤 What is the project slug? Used in hyperlinks. + mypkg +🎤 What is the Python package name? Used as the name of the package and the top-level import. + mypkg +🎤 Do you want to use dynamic versioning of your package or static? Dynamic means that versions + No +🎤 Do you want to use git with a development platform, like GitHub or GitLab? + Yes +🎤 Which development platform are you planning to use? Used to generate certain documentation an + GitHub +🎤 Your or your organization's username on GitHub. Used to generate certain documentation and hy + pyopensci +🎤 Do you want to include documentation for your project and which framework do you want to use? + Sphinx (https://www.pyopensci.org/pyos-sphinx-theme) +🎤 Do you want to use hatch environments for running isolated commands like linting, building do + Yes +🎤 Do you want to lint your code and generally check the formatting of your files? + Yes +🎤 Do you want to use typing annotations and type check your code? + No +🎤 Do you want to test your code? Generally, we strongly recommend that you do, but for a quick + Yes +🎤 Which license do you want to use? Used in the license file. + MIT +🎤 What is the starting year of the project? Used in copyright statements. + 2024 +``` + +### Stay up-to-date The community will likely continue to develop this template. If at any point, you want to adopt those changes for your project, you can update it. Read more about that process