Skip to content

Commit 78168ce

Browse files
ianhiianhi
committed
initial commit
0 parents  commit 78168ce

35 files changed

+1063
-0
lines changed

‎LICENSES/LICENSE

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2021, Ian Hunt-Isaak
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
* Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
* Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
* Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30+

‎LICENSES/napari-LICENSE

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
The setup.cfg is heavily based on the version from Napari
2+
3+
BSD 3-Clause License
4+
5+
Copyright (c) 2018, Napari
6+
All rights reserved.
7+
8+
Redistribution and use in source and binary forms, with or without
9+
modification, are permitted provided that the following conditions are met:
10+
11+
* Redistributions of source code must retain the above copyright notice, this
12+
list of conditions and the following disclaimer.
13+
14+
* Redistributions in binary form must reproduce the above copyright notice,
15+
this list of conditions and the following disclaimer in the documentation
16+
and/or other materials provided with the distribution.
17+
18+
* Neither the name of the copyright holder nor the names of its
19+
contributors may be used to endorse or promote products derived from
20+
this software without specific prior written permission.
21+
22+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎LICENSES/widget-ts-cookiecutter-LICENSE

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
For the parts of the cookiecutter taken from https://github.com/jupyter-widgets/widget-ts-cookiecutter
2+
3+
Copyright (c) 2017 Project Jupyter Contributors
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
1. Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
2. Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
3. Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30+

‎README.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Matplotlib 3rd Party Package Cookiecutter
2+
3+
Turn your matplotlib convenience scripts into a proper python package using this cookiecutter.
4+
5+
```
6+
pip install cookiecutter
7+
cookiecutter gh:ianhi/matplotlib-extension-cookiecutter
8+
```
9+
10+
## Building docs
11+
```
12+
cd docs
13+
make watch
14+
```
15+
16+
## Setting up tests
17+
18+
The best way to do testing for a Matplotlib extension is to use [pytest-mpl](https://github.com/matplotlib/pytest-mpl#about). This project inclues a basic test, but does not pregenerate any baselines images. To make the example test work you first need to generate the baseline with:
19+
20+
```
21+
pytest --mpl-generate-path=<package-name>/tests/baseline
22+
```
23+
24+
For full instructions see: https://github.com/matplotlib/pytest-mpl#using
25+
26+
## Publicizing your package
27+
28+
Once you've made your package other people will likely want to use your hard work, and maybe even contribute to it! But for this to happen they need to know about it. The Matplotlib devs also want you to share your package and like to amplify your advertising. So some great steps to take in order to share your package are:
29+
30+
1. Make a PR to add it to Matplotlib's 3rd party packages page
31+
- [Example PR](https://github.com/matplotlib/matplotlib/pull/13076)
32+
2. Tweet about your pacakge and and mention `@matplotlib` for a retweet.
33+
34+
## Releasing to PyPi
35+
### Manually
36+
First set ensure you have the right packages installed:
37+
```
38+
pip install build twine
39+
```
40+
41+
Then generate an `sdist` and a `wheel`:
42+
43+
1. bump version in `_version.py`
44+
2. `git add <...>/_version.py`
45+
3. `commit -m 'version bump'`
46+
4. `git tag <version number>`
47+
5. `git push --tags`
48+
6. `python -m build -sdist -wheel`
49+
7. `twine upload dist/*`
50+
51+
52+
53+
### Using Github Actions
54+
If you use Github as your Git repository then you can also automate steps 4-7 by using the Github action included in the cookiecutter.
55+
56+
To do this you will need to generate a PyPI api token and add it to your repository's secrets.
57+
58+
**Generating an api token**
59+
60+
Go to you [PyPI account setttings](https://pypi.org/manage/account/), scroll down to the API tokens section and select "Add API token".
61+
62+
**Adding api token to Github Secrets**
63+
Once you've have copied the token from PyPI go the `Secrets` section of your Github repo's settings and add the token with the name `PYPI_API_TOKEN`
64+
65+
66+
With that set up all you need to do to create a release is:
67+
1. bump version in `_version.py`
68+
2. `git add <...>/_version.py`
69+
3. `git commit -m 'version bump' && git push`
70+
4. Make a release using the github release tool.
71+
72+
To make the release go the the `Releases` section in the repo sidebar:
73+
74+
![Arrow pointing to Releases section](imgs/releases1.png)
75+
76+
then draft a new release:
77+
78+
![Arrow pointing to draft release button](imgs/releases2.png)
79+
80+
After you fill out the information the Github action will create a new tag for you, build the wheel, and upload it to PyPI.
81+
82+
83+
## Miscellaneous Advice
84+
85+
Do not use Matplotlib private methods. If you really need the functionality then consider opening a feature request to have Matplotlib provide a public API for what you want.
86+
87+
There is some discussion of how to use Matplotlib docstrings on discourse: https://discourse.matplotlib.org/t/docs-for-a-method-wrapping-a-matplotlib-method/21055
88+
89+
https://colcarroll.github.io/yourplotlib/ is a great read for how to make an extension to Matplotlib.
90+
91+
## LICENSE Advice
92+
93+
You may end up using portions of Matplotlib's code or copying docstrings when making a Matplotlib extension.
94+
95+
As a practical rule: If you end up copying a non-trivial amount of code or docs the safest course of action is to add the Matplotlib license to your project as a derived work. For example see how Matplotlib does it https://github.com/matplotlib/matplotlib/tree/master/LICENSE.
96+
97+
> But what is non-trivial????
98+
99+
100+
practical copyright rules
101+
102+
If it were homework and you didn't acknowledge would it be cheating?
103+
If yes then .... (e..g add a comment and include a license file in ___ folder)
104+
105+
106+
## Credit
107+
108+
This cookiecutter is partially based on the following cookiecutters
109+
- https://github.com/jupyter-widgets/widget-ts-cookiecutter
110+
- The `setup.cfg` from https://github.com/napari/napari
111+
112+
----
113+
Happy Plotting!

‎TODO

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
- MANIFEST.in
2+
- instructions in top level readme
3+
- pre-commit?

‎cookiecutter.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"author_name": "",
3+
"author_email": "",
4+
"github_organization_name": "",
5+
"github_project_name": "",
6+
"python_package_name": "{{ cookiecutter.github_project_name | replace('-', '_') }}",
7+
"project_short_description": "A 3rd party packge for Matplotlib",
8+
"year": "2021",
9+
"_copy_without_render": [
10+
".github/workflows/*"
11+
]
12+
}

‎imgs/releases1.png

32.4 KB
Loading

‎imgs/releases2.png

16.8 KB
Loading

‎{{cookiecutter.github_project_name}}/.github/ISSUE_TEMPLATE/bug_report.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: 🐛 Bug Report
3+
about: Report a bug
4+
# based on matplotlib issue template
5+
---
6+
7+
<!--To help us understand and resolve your issue, please fill out the form to the best of your ability.-->
8+
<!--You can feel free to delete the sections that do not apply.-->
9+
10+
### Bug report
11+
12+
**Bug summary**
13+
14+
<!--A short 1-2 sentences that succinctly describes the bug-->
15+
16+
**Code for reproduction**
17+
18+
<!--A minimum code snippet required to reproduce the bug.
19+
Please make sure to minimize the number of dependencies required, and provide
20+
any necessary plotted data.
21+
22+
```python
23+
# Paste your code here
24+
#
25+
#
26+
```
27+
28+
**Actual outcome**
29+
30+
<!--The output produced by the above code, which may be a screenshot, console output, etc.-->
31+
32+
**Expected outcome**
33+
34+
<!--A description of the expected outcome from the code snippet-->
35+
<!--If this used to work in an earlier version of Matplotlib, please note the version it used to work on-->
36+
37+
**Version Info**
38+
<!--Please specify your platform and versions of the relevant libraries you are using:-->
39+
* Operating system:
40+
* Matplotlib version:
41+
* Matplotlib backend (`print(matplotlib.get_backend())`):
42+
* Python version:
43+
* Jupyter version (if applicable):
44+
* Other libraries:

‎{{cookiecutter.github_project_name}}/.github/ISSUE_TEMPLATE/config.yml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
2+
blank_issues_enabled: true # default
3+
contact_links:
4+
- name: ❓ Question/Support/Other
5+
url: https://discourse.matplotlib.org/c/3rdparty/18
6+
about: If you have a usage question

‎{{cookiecutter.github_project_name}}/.github/ISSUE_TEMPLATE/documentation.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: 📖 Documentation improvement
3+
about: Report parts of the docs that are wrong or unclear
4+
labels: documentation, bug
5+
---
6+
7+
<!--To help us understand and resolve your issue, please fill out the form to the best of your ability.-->
8+
<!--You can feel free to delete the sections that do not apply.-->
9+
10+
### Problem
11+
12+
<!--
13+
If you are referencing an existing piece of documentation or example please provide a link.
14+
15+
* I found [...] to be unclear because [...]
16+
* [...] made me think that [...] when really it should be [...]
17+
* There is no example showing how to do [...]
18+
-->
19+
20+
21+
### Suggested Improvement
22+
23+
<!--
24+
If you have an idea to improve the documentation please suggest it here
25+
26+
* This line should be be changed to say [...]
27+
* Include a paragraph explaining [...]
28+
* Add a figure showing [...]
29+
-->

‎{{cookiecutter.github_project_name}}/.github/ISSUE_TEMPLATE/feature_request.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: 🚀 Enhancement/Feature Request
3+
about: Suggest something that could be improved or a New Feature to add
4+
labels: enhancement
5+
---
6+
7+
<!--
8+
Welcome! Thanks for thinking of a way to improve ${{ cookiecutter.python_package_name }}. If this solves a problem for you, then it probably solves that problem for lots of people! So the whole community will benefit from this request.
9+
10+
11+
Before creating a new feature request please search the issues for relevant feature requests.
12+
-->
13+
14+
### Problem
15+
16+
<!-- Provide a clear and concise description of what problem this feature will solve. For example:
17+
18+
* I'm always frustrated when [...] because [...]
19+
* I would like it if [...] happened when I [...] because [...]
20+
-->
21+
22+
### Proposed Solution
23+
24+
<!-- Provide a clear and concise description of a way to accomplish what you want. For example:
25+
26+
* Add an option so that when [...] [...] will happen
27+
-->
28+
29+
### Additional context
30+
31+
<!-- Add any other context or screenshots about the feature request here. You can also include links to examples of other programs that have something similar to your request. For example:
32+
33+
* Another project [...] solved this by [...]
34+
-->
35+

‎{{cookiecutter.github_project_name}}/.github/workflows/lint.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Lint
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
lint:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v2
14+
- uses: actions/setup-python@v2
15+
- uses: psf/black@stable
16+
with:
17+
args: ". --check"
18+
- name: docstrings
19+
run: |
20+
pip install flit
21+
pushd $(mktemp -d)
22+
git clone https://github.com/Carreau/velin.git --single-branch --depth 1
23+
cd velin
24+
flit install
25+
popd
26+
velin . --check

0 commit comments

Comments
 (0)