Add: package versionioning, pypi / conda publishing & code format pre-commit pages (Reviews Welcome!)

.all-contributorsrc

@@ -243,12 +243,62 @@
         "code",
         "review"
       ]
+    },
+    {
+      "login": "dhirschfeld",
+      "name": "Dave Hirschfeld",
+      "avatar_url": "https://avatars.githubusercontent.com/u/881019?v=4",
+      "profile": "https://dhirschfeld.github.io",
+      "contributions": [
+        "review"
+      ]
+    },
+    {
+      "login": "ucodery",
+      "name": "Jeremy Paige",
+      "avatar_url": "https://avatars.githubusercontent.com/u/28751151?v=4",
+      "profile": "http://blog.ucodery.com",
+      "contributions": [
+        "code",
+        "review"
+      ]
+    },
+    {
+      "login": "abravalheri",
+      "name": "Anderson Bravalheri",
+      "avatar_url": "https://avatars.githubusercontent.com/u/320755?v=4",
+      "profile": "https://github.com/abravalheri",
+      "contributions": [
+        "code",
+        "design"
+      ]
+    },
+    {
+      "login": "dpprdan",
+      "name": "Daniel Possenriede",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1423562?v=4",
+      "profile": "https://possenrie.de",
+      "contributions": [
+        "code",
+        "review"
+      ]
+    },
+    {
+      "login": "yang-ruoxi",
+      "name": "ruoxi",
+      "avatar_url": "https://avatars.githubusercontent.com/u/13646711?v=4",
+      "profile": "https://github.com/yang-ruoxi",
+      "contributions": [
+        "code",
+        "review"
+      ]
     }
   ],
   "contributorsPerLine": 7,
   "skipCi": true,
   "repoType": "github",
   "repoHost": "https://github.com",
   "projectName": "python-package-guide",
-  "projectOwner": "pyOpenSci"
+  "projectOwner": "pyOpenSci",
+  "commitType": "docs"
 }

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.4
+    rev: v2.2.5
     hooks:
     - id: codespell
       additional_dependencies:

README.md

@@ -1,6 +1,6 @@
 # <img src="images/logo/logo.png" width=40 /> pyOpenSci Scientific Python Open Source Packaging Guide
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-23-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-28-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
@@ -106,6 +106,11 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://code.scienxlab.org"><img src="https://avatars.githubusercontent.com/u/1692372?v=4?s=100" width="100px;" alt="Matt Hall"/><br /><sub><b>Matt Hall</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=kwinkunks" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Akwinkunks" title="Reviewed Pull Requests">👀</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jezdez"><img src="https://avatars.githubusercontent.com/u/1610?v=4?s=100" width="100px;" alt="Jannis Leidel"/><br /><sub><b>Jannis Leidel</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=jezdez" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Ajezdez" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://dhirschfeld.github.io"><img src="https://avatars.githubusercontent.com/u/881019?v=4?s=100" width="100px;" alt="Dave Hirschfeld"/><br /><sub><b>Dave Hirschfeld</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Adhirschfeld" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://blog.ucodery.com"><img src="https://avatars.githubusercontent.com/u/28751151?v=4?s=100" width="100px;" alt="Jeremy Paige"/><br /><sub><b>Jeremy Paige</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=ucodery" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Aucodery" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/abravalheri"><img src="https://avatars.githubusercontent.com/u/320755?v=4?s=100" width="100px;" alt="Anderson Bravalheri"/><br /><sub><b>Anderson Bravalheri</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=abravalheri" title="Code">💻</a> <a href="#design-abravalheri" title="Design">🎨</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://possenrie.de"><img src="https://avatars.githubusercontent.com/u/1423562?v=4?s=100" width="100px;" alt="Daniel Possenriede"/><br /><sub><b>Daniel Possenriede</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=dpprdan" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Adpprdan" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/yang-ruoxi"><img src="https://avatars.githubusercontent.com/u/13646711?v=4?s=100" width="100px;" alt="ruoxi"/><br /><sub><b>ruoxi</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=yang-ruoxi" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Ayang-ruoxi" title="Reviewed Pull Requests">👀</a></td>
     </tr>
   </tbody>
 </table>

conf.py

@@ -51,15 +51,15 @@
 
 # Link to our repo for easy PR/ editing
 html_theme_options = {
-    "announcement": "🚧 This guide is currently under heavy construction 🚧 ",
+    "announcement": "<p><a href='https://www.pyopensci.org/software-peer-review/about/intro.html'>Submit Your Python Package for Peer Review - Learn More!</a></p>🚧 This guide is currently being developed! 🚧 ",
     "external_links": [
         {
             "url": "https://www.pyopensci.org",
             "name": "pyOpenSci Website",
         },
         {
-            "url": "https://www.pyopensci.org/python-package-guide",
-            "name": "Python Packaging Guide",
+            "url": "https://www.pyopensci.org/software-peer-review",
+            "name": "Peer Review Guide",
         },
         {
             "url": "https://pyopensci.org/governance",
@@ -75,10 +75,11 @@
     ],
     "logo": {
         "text": "Python Package Guide",
-        "image_dark": "logo.png",
-        "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is blue and yellow following the Python logo",
+        "image_dark": "logo-dark-mode.png",
+        "image_light": "logo-light-mode.png",
+        "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is a purple flower with pyOpenSci under it. The o in open sci is the center of the flower",
     },
-    "header_links_before_dropdown": 4,
+    "header_links_before_dropdown": 3,
     "use_edit_page_button": True,
     "show_toc_level": 1,
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
@@ -128,6 +129,5 @@
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
 html_css_files = ["pyos.css"]
-html_title = "pyOpenSci Python Packaging Guide"
+html_title = "Python Packaging Guide"
 html_js_files = ["matomo.js"]
-html_logo = "images/logo/logo.png"

documentation/hosting-tools/myst-markdown-rst-doc-syntax.md

@@ -2,7 +2,7 @@
 
 There are three commonly used syntaxes for creating Python documentation:
 1. [markdown](https://www.markdownguide.org/): Markdown is an easy-to-learn text
-syntax. It is the default syntax use in Jupyter Notebooks. There are tools that you can add to a Sphinx website that allow it to render markdown as html. However, using markdown to write documentation has limitations. For instance if you want to add references,
+syntax. It is the default syntax used in Jupyter Notebooks. There are tools that you can add to a Sphinx website that allow it to render markdown as html. However, using markdown to write documentation has limitations. For instance if you want to add references,
 colored call out blocks and other custom elements to your documentation, you will
 need to use either **myST** or **rST**.
 1. [rST (ReStructured Text):](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). **rST** is the native syntax that sphinx supports. rST was the default syntax used for documentation for many years. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows.
@@ -14,7 +14,7 @@ While you can chose to use any of the syntaxes listed above, we suggest using
 
 * It is a simpler syntax and thus easier to learn;
 * The above simplicity will make it easier for more people to contribute to your documentation.
-* Most of your corePythonpackage text files, such as your README.md file, are already in `.md` format
+* Most of your core Python package text files, such as your README.md file, are already in `.md` format
 * `GitHub` and `Jupyter Notebooks` support markdown thus it's more widely used in the scientific ecosystem.
 
 

documentation/hosting-tools/publish-documentation-online.md

@@ -37,7 +37,7 @@ However, you will need to do a bit more work to build and deploy your
 documentation if you use GitHub pages.
 
 Read the Docs can be setup in your Read the Docs user account. The service
-and automates the entire process of building and deploying your documentation.
+automates the entire process of building and deploying your documentation.
 
 If you don't want to maintain a documentation website for your Python package,
 we suggest using the Read the Docs website.

documentation/hosting-tools/website-hosting-optimizing-your-docs.md

@@ -8,7 +8,7 @@ engines such as Google find your documentation.
 
 ```{important}
 
-Google analytics [is not compliant with the European General Data Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-analytics-4-gdpr/). While there are many components to this regulation, one of the core elements is that you have to let users know on your site that you are collecting data and they have to consent. WHile it is possible to add infrastructure around Google Analytics to make it close to following GDPR regulations, the community is slowly shifting away from Google using open tools such as [Plausible](https://plausible.io/), [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and [Matomo](https://matomo.org) for web analytics.
+Google analytics [is not compliant with the European General Data Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-analytics-4-gdpr/). While there are many components to this regulation, one of the core elements is that you have to let users know on your site that you are collecting data and they have to consent. While it is possible to add infrastructure around Google Analytics to make it close to following GDPR regulations, the community is slowly shifting away from Google using open tools such as [Plausible](https://plausible.io/), [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and [Matomo](https://matomo.org) for web analytics.
 
 pyOpenSci is currently looking into free options for open source
 developers.
@@ -35,7 +35,7 @@ more visible to others when they search.
 
 This extension is lightweight.
 
-It [requires that you to add it to your Sphinx `conf.py` extension list and site your documentation base url.](https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html).
+It [requires that you to add it to your Sphinx `conf.py` extension list and site your documentation base url](https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html).
 
 ### [sphinxext.opengraph](https://github.com/wpilibsuite/sphinxext-opengraph)
 

documentation/repository-files/readme-file-best-practices.md

@@ -116,7 +116,7 @@ file.
 Include instructions for installing your package. If you have published
 the package on both PyPI and Anaconda Cloud be sure to include instructions for both.
 
-### ✔️ Document any addition setup required
+### ✔️ Document any additional setup required
 
 Add any additional setup required such as authentication tokens, to
 get started using your package. If setup is complex, consider linking to an

documentation/write-user-documentation/create-package-tutorials.md

@@ -35,10 +35,10 @@ may enjoy using Sphinx gallery. Sphinx gallery uses **.py** files with
 text and code sections that mimic the Jupyter Notebook format. When you build
 your documentation, the gallery extension:
 
-1. Runs the code in each tutorial. Running your tutorial this acts as a check to ensure your package functions and classes (ie the API) are working as they should.
+1. Runs the code in each tutorial. Running your tutorial like this acts as a check to ensure your package's functions, classes, methods, and attributes (ie the API) are working as they should.
 1. Creates a downloadable Jupyter Notebook **.ipynb** file and a  **.py** script for your tutorial that a user can quickly download and run.
 1. Creates a rendered  **.html** page with the code elements and code outputs in a user-friendly tutorial gallery.
-1. Creates a gallery landing page with visual thumbnails for each tutorial that you create
+1. Creates a gallery landing page with visual thumbnails for each tutorial that you create.
 
 
 ```{figure} /images/sphinx-gallery-overview.png
@@ -64,26 +64,26 @@ python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bot
 ```
 
 ### Sphinx Gallery benefits
-* easy-to-download notebook and .py outputs for each tutorials
+* easy-to-download notebook and .py outputs for each tutorials.
 * .py files are easy to work with in the GitHub pull request environment.
-* Nice gridded gallery output
-* Build execution time data per tutorial [Example](https://sphinx-gallery.github.io/stable/auto_examples/sg_execution_times.html)
+* Nice gridded gallery output.
+* Build execution time data per tutorial. [Example](https://sphinx-gallery.github.io/stable/auto_examples/sg_execution_times.html)
 
 #### Sphinx gallery challenges
 
 The downsides of using Sphinx gallery include:
 
 * the **.py** files can be finicky to configure, particularly if you have matplotlib plot outputs.
 
-For example: To make allow for plots to render, you need to name each file with `plot_`
+For example: To allow for plots to render, you need to name each file with `plot_`
 at the beginning.
 
 * Many users these days are used to working in Jupyter Notebooks. .py may be slightly less user friendly to work with
 
 These nuances can make it challenging for potential contributors to add
 tutorials to your package. This can also present maintenance challenge.
 
-Add about the gallery setup -
+Add about the gallery setup:
 
 ```bash
 $ docs % make html
@@ -129,7 +129,7 @@ width: 80%
 alt: Image showing the gallery output provided by nbsphinx using the sphinx-gallery front end interface.
 ---
 `nbsphinx` can be combined with Sphinx gallery to create a gallery of tutorials.
-However, rather render the gallery as a grid, it lists all of the gallery
+However, rather than rendering the gallery as a grid, it lists all of the gallery
 elements in a single column.
 ```