update contribute guide and readme (#9)

* update contribute guide and readme

* update release checklist

* update codespell checks

* update mypy checks

Author: mdtanker

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -12,6 +12,10 @@ assignees: ''
 <!-- Optional -->
 **Target date:** YYYY/MM/DD
 
+## Update dependencies
+
+- [ ] Check all the dependency changes since the last release are  reflected in `environment.yml`
+
 ## Draft a Zenodo archive (to be done by a manager on Zenodo)
 
 - [ ] Go to the Zenodo entry for this project (find the link to the latest Zenodo release on the `README.md` file)
@@ -28,7 +32,7 @@ assignees: ''
 ## Update the changelog
 
 - [ ] Generate a list of commits between the last release tag and now: `git log HEAD...v1.2.3 > changes.md`
-- [ ] Use this to summary the major changes to the code and add short descriptions to `CHANGELOG.md` (not `docs/changelog.md`!).
+- [ ] Use this to summarize the major changes to the code and add short descriptions to `CHANGELOG.md` (not `docs/changelog.md`!).
 - [ ] Add the release date and Zenodo DOI badge to the top
 - [ ] Add contributors to the list
 - [ ] Open a PR to update the changelog

.pre-commit-config.yaml

@@ -67,6 +67,9 @@ repos:
       - id: codespell
         additional_dependencies:
           - tomli; python_version<'3.11'
+        entry:
+          codespell --ignore-regex='[A-Za-z0-9+/]{100,}'
+          --skip="*.js,*.html,*.css,*.svg"
 
   - repo: https://github.com/shellcheck-py/shellcheck-py
     rev: "v0.10.0.1"

CONTRIBUTING.md

@@ -2,11 +2,13 @@
 
 ## TLDR (Too long; didn't read)
 * [fork](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) the [repository](https://github.com/organizationname/samplepackagename) using the `Fork` button on GitHub.
-* clone your forked repository on your computer with `git clone https://github.com/organizationname/samplepackagename`.
-* [create a branch](https://docs.github.com/en/get-started/using-github/github-flow#create-a-branch) for your edits with `git branch new-branch`
-* make your changes and run the style checkers with `nox -s style`
-* once the style checks pass, commit your changes with `git commit -m "a short description of your changes"`
-* push your changes with `git push -u origin new-branch`
+* clone your forked repository on your computer: `git clone https://github.com/organizationname/samplepackagename`.
+* [create a branch](https://docs.github.com/en/get-started/using-github/github-flow#create-a-branch) for your edits: `git checkout -b new-branch`
+* make your changes
+* run the style checkers: `nox -s style`
+* add your changed files: `git add .`
+* once the style checks pass, commit your changes: `git commit -m "a short description of your changes"`
+* push your changes: `git push -u origin new-branch`
 * [make a Pull Request](http://makeapullrequest.com/) for your branch from the main GitHub repository [PR page](https://github.com/organizationname/samplepackagename/pulls).
 
 🎉 Thanks for considering contributing to this package! 🎉
@@ -53,7 +55,6 @@ contributions.
   - [Code review](#code-review)
 * [Publish a new release](#publish-a-new-release)
 * [Update the Dependencies](#update-the-dependencies)
-* [Release Checklist](#release-checklist)
 
 ## What Can I Do?
 
@@ -192,7 +193,7 @@ This environment now contains your local, editable version of samplepackagename,
 Instead of editing the main branch, which should remain stable, we create a `branch` and edit that. To create a new branch, called `new-branch` use the following command:
 
 ```bash
-git branch new-branch
+git checkout -b new-branch
 ```
 
 ### Make your changes
@@ -277,9 +278,9 @@ Leave a comment in the PR and we'll help you out.
 
 ### Documentation
 
-The Docs are build with `Sphinx` and `Read the Docs`.
+The Docs are build with [Sphinx](https://www.sphinx-doc.org/en/master/) and hosted on [GitHub Pages](https://pages.github.com/).
 
-> **Note:** The docs are automatically built on PR's by `RTD`, but it's good practice to build them manually before a PR, to check them for errors.
+> **Note:** The docs are automatically built on each commit to a PR, but if you've made significant changes to the docs its good practice to build them manually before a PR, to check them for errors.
 
 #### Check the build manually (optional)
 
@@ -292,16 +293,11 @@ You can build the docs using:
     nox -s docs
 ```
 
-or if you don't want them to automatically update
-```bash
-    nox -s docs --non-interactive
-```
+Click the link to open your docs in a website which will automatically update as you make edits.
 
 #### Automatically build the docs
 
-Add, commit, and push all changes to GitHub in a Pull Request, and `RTD` should automatically build the docs.
-
-In each PR, you will see section of the checks for `RTD`. Click on this to preview the docs for the PR.
+Add, commit, and push all changes to GitHub in a Pull Request, and the docs should automatically be updated. If the PR can from the same repository (not a fork), then a preview of the updated docs should be available after a few minutes.
 
 ### Committing changes
 
@@ -382,6 +378,9 @@ This will almost always be done by the developers, but as a guide for them, here
 
 Follow all the above instructions for formatting. Push your changes to a new or existing Pull Request. Once the automated GitHub Actions run (and pass), merge the PR into the main branch.
 
+Open a new issue, selecting the `Release-Checklist` template, and follow the direction there.
+
+
 ### PyPI (pip)
 PyPI release are made automatically via GitHub actions whenever a pull request is merged.
 
@@ -395,13 +394,3 @@ Once the new version is on conda, update the binder .yml file, as below.
 To add or update a dependencies, add it to `pyproject.toml` either under `dependencies` or `optional-dependencies`. This will be included in the next build uploaded to PyPI.
 
 If you add a dependency necessary for using the package, make sure to add it to the Binder config file and update the `environment.yml` file in the repository. See below.
-
-## Release Checklist
-* re-run any relevant notebooks
-* check docs are building correctly using the GitHub actions link within the PR
-* merge the  PR
-* wait for `PyPI` to publish the new version [here](https://pypi.python.org/pypi/samplepackagename)
-* wait for a PR to be opened in the [feedstock](https://github.com/conda-forge/samplepackagename-feedstock)
-* update any changed dependencies in the feedstock PR and merge
-* wait for `conda` to publish the new version [here](https://anaconda.org/conda-forge/samplepackagename)
-* manually add dependency changes to `environment.yml`

README.md

@@ -145,6 +145,7 @@ Steps:
     - for `Branch`, choose "gh-pages"
     - for `Select folder`, choose "root"
     - optionally choose a custom URL and hit save
+    - in each PR there should be a preview for the new site
     - for every push to `main` (from a PR), the site will be updated
 14) Finalize
     - remove all the above instructions and raise any issues in this template's repository if you have any suggestion or found any errors in this template!
@@ -174,8 +175,8 @@ Short description of your package.
 [pypi-link]:                https://pypi.org/project/samplepackagename/
 [pypi-platforms]:           https://img.shields.io/pypi/pyversions/samplepackagename
 [pypi-version]:             https://img.shields.io/pypi/v/samplepackagename
-[website-badge]:            https://github.com/mdtanker/python_package_template/actions/workflows/pages/pages-build-deployment/badge.svg
-[website-link]:             https://mdtanker.github.io/python_package_template/
+[website-badge]:            https://github.com/organizationname/samplepackagename/actions/workflows/pages/pages-build-deployment/badge.svg
+[website-link]:             https://organizationname.github.io/samplepackagename/
 
 <!-- prettier-ignore-end -->
 

pyproject.toml

@@ -102,6 +102,8 @@ enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
 warn_unreachable = true
 disallow_untyped_defs = false
 disallow_incomplete_defs = false
+ignore_missing_imports = true
+disallow_untyped_decorators = false
 
 [[tool.mypy.overrides]]
 module = "samplepackagename.*"
@@ -161,3 +163,6 @@ messages_control.disable = [
   "missing-function-docstring",
   "wrong-import-position",
 ]
+
+[tool.codespell]
+ignore-words-list = ["word_to_ignore"]