From efb48497781d1832f3766c37aff7b3da6e135d4b Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 25 Jan 2023 13:31:02 -0700 Subject: [PATCH 1/2] Add: precommit and clean up all files --- .circleci/config.yml | 2 +- .github/workflows/build-book.yml | 6 +- .pre-commit-config.yaml | 41 ++++++ CONTRIBUTING.md | 18 +-- README.md | 8 +- _static/pyos.css | 2 +- _templates/header.html | 3 +- ci-and-testing/intro.md | 2 +- code-style-structure/intro.md | 2 +- codespell-ignore.txt | 1 + conf.py | 12 +- documentation/hosting-tools/intro.md | 18 +-- .../myst-markdown-rst-doc-syntax.md | 26 ++-- .../publish-documentation-online.md | 43 +++---- ...hinx-python-package-documentation-tools.md | 42 +++--- .../website-hosting-optimizing-your-docs.md | 54 ++++---- documentation/index.md | 108 ++++++++-------- .../repository-files/code-of-conduct-file.md | 42 +++--- .../repository-files/contributing-file.md | 19 ++- .../repository-files/development-guide.md | 38 +++--- documentation/repository-files/intro.md | 23 ++-- .../repository-files/license-files.md | 28 ++-- .../readme-file-best-practices.md | 118 ++++++++--------- .../create-package-tutorials.md | 116 +++++++++-------- .../document-your-code-api-docstrings.md | 120 +++++++++--------- .../write-user-documentation/get-started.md | 62 ++++----- .../write-user-documentation/intro.md | 15 +-- index.md | 56 ++++---- noxfile.py | 8 +- pyproject.toml | 4 + python-packaging/intro.md | 10 +- requirements.txt | 2 +- 32 files changed, 540 insertions(+), 509 deletions(-) create mode 100644 .pre-commit-config.yaml create mode 100644 codespell-ignore.txt create mode 100644 pyproject.toml diff --git a/.circleci/config.yml b/.circleci/config.yml index 1e795c55..13ff348b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -12,7 +12,7 @@ jobs: pip install nox pip list - run: - name: Build book html + name: Build book html command: nox -s docs - store_artifacts: diff --git a/.github/workflows/build-book.yml b/.github/workflows/build-book.yml index 99fe5e21..cf10fb09 100644 --- a/.github/workflows/build-book.yml +++ b/.github/workflows/build-book.yml @@ -1,7 +1,7 @@ name: build-test-deploy-book # Only build PRs, the main branch, and releases. Pushes to branches will only -# be built when a PR is opened. This avoids duplicated buids in PRs comming +# be built when a PR is opened. This avoids duplicated buids in PRs coming # from branches in the origin repository (1 for PR and 1 for push). # This came from Leo's work with fatiando on: @@ -53,7 +53,7 @@ jobs: _build/html/ # Push the book's HTML to github-pages - - name: Push to GitHub Pages + - name: Push to GitHub Pages # Only push if on main branch if: github.ref == 'refs/heads/main' uses: peaceiris/actions-gh-pages@v3.8.0 @@ -69,5 +69,3 @@ jobs: arguments: | --ignore-files "/.+\/_static\/.+/,/genindex.html/" --ignore-status-codes "404, 403, 503" - - diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..525e715a --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,41 @@ +# pre-commit is a tool that you run locally +# to perform a predefined set of tasks manually and/or +# automatically before git commits are made. +# Here we are using pre-commit with the precommit.ci bot to implement +# code fixes automagically in pr's. You will still want to install pre-commit +# to run locally +# Config reference: https://pre-commit.com/#pre-commit-configyaml---top-level +# To run on a pr, add a comment with the text "pre-commit.ci run" +# Common tasks +# +# - Run on all files: pre-commit run --all-files +# - Register git hooks: pre-commit install --install-hooks + +ci: + autofix_prs: false + #skip: [flake8, end-of-file-fixer] + autofix_commit_msg: | + '[pre-commit.ci 🤖] Apply code format tools to PR' + # Update hook versions every quarter (so we don't get hit with weekly update pr's) + autoupdate_schedule: quarterly + +repos: + + # Misc commit checks + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + # ref: https://github.com/pre-commit/pre-commit-hooks#hooks-available + hooks: + # Autoformat: Makes sure files end in a newline and only a newline. + - id: end-of-file-fixer + # Lint: Check for files with names that would conflict on a + # case-insensitive filesystem like MacOS HFS+ or Windows FAT. + - id: check-case-conflict + - id: trailing-whitespace + + - repo: https://github.com/codespell-project/codespell + rev: v2.2.2 + hooks: + - id: codespell + additional_dependencies: + - tomli diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d792b9c2..6d8dfb64 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,25 +1,25 @@ -# Contributing Guide for the Python open source software packaging book +# Contributing Guide for the Python open source software packaging book This is a community resource. We welcome contributions in the form of issues and/or pull requests to this guide. -* If you have an idea for something that should be included in the guide, [please open an issue here](https://github.com/pyOpenSci/python-package-guide/issues). -* If you find a typo, feel free to [submit a pull request](https://github.com/pyOpenSci/python-package-guide/pulls) to modify the text directly. Or, if you are less comfortable with pull requests, feel free to open an issue. -* If you want to see a larger change to the content of the guide book, please submit an issue first! +* If you have an idea for something that should be included in the guide, [please open an issue here](https://github.com/pyOpenSci/python-package-guide/issues). +* If you find a typo, feel free to [submit a pull request](https://github.com/pyOpenSci/python-package-guide/pulls) to modify the text directly. Or, if you are less comfortable with pull requests, feel free to open an issue. +* If you want to see a larger change to the content of the guide book, please submit an issue first! ## How this guide structured Most of this repository is structured for **Sphinx**, a documentation engine built in `Python`. We are using the Sphinx Book Theme and the `myST` syntax to create each page in this book. -If you wish to contribute by working on the guide book locally, you -will first need to +If you wish to contribute by working on the guide book locally, you +will first need to -1. Fork this repository +1. Fork this repository 2. Clone it locally -3. Build the documentation locally +3. Build the documentation locally ## Instructions for building the documentation locally on your computer -The easiest way to build the documentation in this repository is to use `nox`, +The easiest way to build the documentation in this repository is to use `nox`, a tool for quickly building environments and running commands within them. Nox ensures that your environment has all the dependencies needed to build the documentation. diff --git a/README.md b/README.md index aef5aa26..eee95787 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,11 @@ pyOpenSci is devoted to building diverse, supportive community around the Python open source tools that drive open science. We do this through: * open peer review -* mentorship and +* mentorship and * training. -pyOpenSci is an independent organization, fiscally sponsored by Community -Initiatives. +pyOpenSci is an independent organization, fiscally sponsored by Community +Initiatives. :construction: Construction note :construction: @@ -97,4 +97,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! \ No newline at end of file +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! diff --git a/_static/pyos.css b/_static/pyos.css index 73f10969..6bfeb1af 100644 --- a/_static/pyos.css +++ b/_static/pyos.css @@ -41,4 +41,4 @@ figcaption { .admonition p { font-size: 1.1em; font-weight: bold; - } \ No newline at end of file + } diff --git a/_templates/header.html b/_templates/header.html index 778c419e..8fc674b9 100644 --- a/_templates/header.html +++ b/_templates/header.html @@ -3,5 +3,4 @@ - - + diff --git a/ci-and-testing/intro.md b/ci-and-testing/intro.md index 39100843..00d5867f 100644 --- a/ci-and-testing/intro.md +++ b/ci-and-testing/intro.md @@ -4,4 +4,4 @@ This section is evolving and should be published by the end of Spring 2023 -coming soon \ No newline at end of file +coming soon diff --git a/code-style-structure/intro.md b/code-style-structure/intro.md index 7f540b30..f2e918b7 100644 --- a/code-style-structure/intro.md +++ b/code-style-structure/intro.md @@ -1,4 +1,4 @@ # Code style and structure -Under development \ No newline at end of file +Under development diff --git a/codespell-ignore.txt b/codespell-ignore.txt new file mode 100644 index 00000000..098db59d --- /dev/null +++ b/codespell-ignore.txt @@ -0,0 +1 @@ +aways diff --git a/conf.py b/conf.py index 2c970231..562d5c3c 100644 --- a/conf.py +++ b/conf.py @@ -74,11 +74,11 @@ # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ - "_build", - "Thumbs.db", - ".DS_Store", - ".github", - ".nox", + "_build", + "Thumbs.db", + ".DS_Store", + ".github", + ".nox", "README.md" ] @@ -99,4 +99,4 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] \ No newline at end of file +html_static_path = ['_static'] diff --git a/documentation/hosting-tools/intro.md b/documentation/hosting-tools/intro.md index 740a4b6d..147b6900 100644 --- a/documentation/hosting-tools/intro.md +++ b/documentation/hosting-tools/intro.md @@ -1,17 +1,17 @@ -# Tools to Build and Host your Documentation +# Tools to Build and Host your Documentation -The most common tool for building documentation in the Python -ecosystem currently is Sphinx. However, some maintainers -are using tools like [mkdocs](https://www.mkdocs.org/) for documentation. It is +The most common tool for building documentation in the Python +ecosystem currently is Sphinx. However, some maintainers +are using tools like [mkdocs](https://www.mkdocs.org/) for documentation. It is up to you to use the platform that you prefer for your documentation! -In this section, we introduce Sphinx as a common tool to -build documentation. We talk about various syntax options that you can use +In this section, we introduce Sphinx as a common tool to +build documentation. We talk about various syntax options that you can use when writing Sphinx documentation including mySt and rST. -We also talk about ways to publish your -documentation online and Sphinx tools that might help you optimize -your documentation website. +We also talk about ways to publish your +documentation online and Sphinx tools that might help you optimize +your documentation website. ## Documentation build tools outline diff --git a/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md b/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md index d77a1dda..37b6b347 100644 --- a/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md +++ b/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md @@ -1,29 +1,29 @@ -# Documentation syntax: markdown vs. myST vs. rst syntax to create your docs +# Documentation syntax: markdown vs. myST vs. rst syntax to create your docs 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, -colored call out blocks and other custom elements to your documentation, you will +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, +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. -1. [myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a combination of vanilla of `markdown` and `rST` syntax. It is a nice option if you are comfortable writing markdown. `myst` is preferred by many because it offers both the rich functionality -of rST combined with a simple-to-write markdown syntax. +1. [myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a combination of vanilla of `markdown` and `rST` syntax. It is a nice option if you are comfortable writing markdown. `myst` is preferred by many because it offers both the rich functionality +of rST combined with a simple-to-write markdown syntax. -While you can chose to use any of the syntaxes listed above, we suggest using +While you can chose to use any of the syntaxes listed above, we suggest using `myST` because: * 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. +* 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 -* `GitHub` and `Jupyter Notebooks` support markdown thus it's more widely used in the scientific ecosystem. +* `GitHub` and `Jupyter Notebooks` support markdown thus it's more widely used in the scientific ecosystem. ```{tip} -If you are on the fence about myST vs rst, you might find that **myST** is easier -for more people to contribute to. +If you are on the fence about myST vs rst, you might find that **myST** is easier +for more people to contribute to. ``` - diff --git a/documentation/hosting-tools/publish-documentation-online.md b/documentation/hosting-tools/publish-documentation-online.md index df3220f8..748e4ea7 100644 --- a/documentation/hosting-tools/publish-documentation-online.md +++ b/documentation/hosting-tools/publish-documentation-online.md @@ -1,44 +1,43 @@ # How to publish your Python package documentation online -We suggest that you setup a hosting service for your Python package +We suggest that you setup a hosting service for your Python package documentation. Two free and commonly used ways to -quickly create a documentation website hosting environment are below. +quickly create a documentation website hosting environment are below. -1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service. +1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service. 1. You can host your documentation using [Read the Docs](https://readthedocs.org/). ## What is Read the Docs ? -[Read the Docs](https://readthedocs.org/) is a documentation hosting service that supports publishing your project's documentation. +[Read the Docs](https://readthedocs.org/) is a documentation hosting service that supports publishing your project's documentation. -Read the Docs is a fully featured, free, documentation hosting +Read the Docs is a fully featured, free, documentation hosting service. Some of its many features include: * Is free to host your documentation (but there are also paid tiers if you wish to customize hosting) -* Automates building your documentation +* Automates building your documentation * Allows you to turn on integration with pull requests where you can view documentation build progress (success vs failure). -* Supports versioning of your documentation which allows users to refer to older tagged versions of the docs if they are using older versions of your package. -* Supports downloading of documentation in PDF and other formats. -* You can customize the documentation build using a **.readthedocs.yaml** file in your GitHub repository. +* Supports versioning of your documentation which allows users to refer to older tagged versions of the docs if they are using older versions of your package. +* Supports downloading of documentation in PDF and other formats. +* You can customize the documentation build using a **.readthedocs.yaml** file in your GitHub repository. ## What is GitHub Pages? -[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) is a free web -hosting service offered by GitHub. Using GitHub pages, you can build your -documentation locally or using a Continuous Integration setup, and then push -to a branch in your GitHub repository that is setup to run the GitHub Pages -web build. +[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) is a free web +hosting service offered by GitHub. Using GitHub pages, you can build your +documentation locally or using a Continuous Integration setup, and then push +to a branch in your GitHub repository that is setup to run the GitHub Pages +web build. -## Read the Docs vs GitHub Pages +## Read the Docs vs GitHub Pages -GitHub pages is a great option for your documentation deployment. -However, you will need to do a bit more work to build and deploy your -documentation if you use GitHub pages. +GitHub pages is a great option for your documentation deployment. +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. +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. -If you don't want to maintain a documentation website for your Python package, +If you don't want to maintain a documentation website for your Python package, we suggest using the Read the Docs website. - diff --git a/documentation/hosting-tools/sphinx-python-package-documentation-tools.md b/documentation/hosting-tools/sphinx-python-package-documentation-tools.md index 72bb2a8d..1e1f54d9 100644 --- a/documentation/hosting-tools/sphinx-python-package-documentation-tools.md +++ b/documentation/hosting-tools/sphinx-python-package-documentation-tools.md @@ -1,25 +1,25 @@ # Using Sphinx to Build Python Package Documentation - - -On this page we discuss using [Sphinx](https://www.sphinx-doc.org/) to build your user-facing -package documentation. While Sphinx is currently the most -commonly-used tool in the scientific Python ecosystem, you -are welcome to explore other tools to build documentation -such as [mkdocs](https://www.mkdocs.org/) which is gaining -popularity in the Python packaging ecosystem. +On this page we discuss using [Sphinx](https://www.sphinx-doc.org/) to build your user-facing +package documentation. While Sphinx is currently the most +commonly-used tool in the scientific Python ecosystem, you +are welcome to explore other tools to build documentation +such as [mkdocs](https://www.mkdocs.org/) which is gaining +popularity in the Python packaging ecosystem. ```{tip} Examples of documentation websites that we love: @@ -33,14 +33,14 @@ Examples of documentation websites that we love: ## Sphinx - a static site generator -Sphinx is a [static-site generator](https://www.cloudflare.com/learning/performance/static-site-generator/). A static site generator is a tool that creates -html for a website based upon a set of templates. The html files are then served "Statically" which means that there is no generation or modification of the files on the fly. +Sphinx is a [static-site generator](https://www.cloudflare.com/learning/performance/static-site-generator/). A static site generator is a tool that creates +html for a website based upon a set of templates. The html files are then served "Statically" which means that there is no generation or modification of the files on the fly. -Sphinx is written using Python. +Sphinx is written using Python. -### Sphinx sites can be customized using extensions and themes +### Sphinx sites can be customized using extensions and themes -The functionality of Sphinx can be extended using extensions +The functionality of Sphinx can be extended using extensions and themes. A few examples include: * You can apply documentation themes for quick generation of beautiful documentation. @@ -48,13 +48,13 @@ and themes. A few examples include: * You can [run and test code examples in your docstrings using the doctest extension](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) * While Sphinx natively supports the `rST` syntax. You can add custom syntax parsers to support easier-to-write syntax using tools such as [the MyST parser](https://myst-parser.readthedocs.io/). -### Commonly used Sphinx themes +### Commonly used Sphinx themes -You are free to use whatever Sphinx theme that you prefer. -However, the most common Sphinx themes used in the Python -scientific community include: +You are free to use whatever Sphinx theme that you prefer. +However, the most common Sphinx themes used in the Python +scientific community include: -* [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/) +* [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/) * [sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/) * [furo](https://pradyunsg.me/furo/quickstart/) @@ -63,5 +63,3 @@ scientific community include: This book is created using Sphinx and the `furo` theme. ``` - - diff --git a/documentation/hosting-tools/website-hosting-optimizing-your-docs.md b/documentation/hosting-tools/website-hosting-optimizing-your-docs.md index fc85f963..7f675502 100644 --- a/documentation/hosting-tools/website-hosting-optimizing-your-docs.md +++ b/documentation/hosting-tools/website-hosting-optimizing-your-docs.md @@ -1,36 +1,36 @@ # Optimizing your documentation so search engines (and other users) find it -If you are interested in more people finding your package, you may want to -add some core Sphinx extensions (and theme settings) that will help search -engines such as Google find your documentation. +If you are interested in more people finding your package, you may want to +add some core Sphinx extensions (and theme settings) that will help search +engines such as Google find your documentation. ### Google Analytics -```{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. +```{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. -pyOpenSci is currently looking into free options for open source -developers. +pyOpenSci is currently looking into free options for open source +developers. ``` -Some of the [sphinx themes such as the `pydata-sphinx-theme` and -sphinx-book-theme have built in support for Google Analytics](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/analytics.html#google-analytics). However, if the theme that you chose does not offer -Google Analytics support, you can use the [`sphinxcontrib-gtagjs` extension](https://github.com/attakei/sphinxcontrib-gtagjs). -This extension will add a Google Analytics site tag to each page of your -documentation. +Some of the [sphinx themes such as the `pydata-sphinx-theme` and +sphinx-book-theme have built in support for Google Analytics](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/analytics.html#google-analytics). However, if the theme that you chose does not offer +Google Analytics support, you can use the [`sphinxcontrib-gtagjs` extension](https://github.com/attakei/sphinxcontrib-gtagjs). +This extension will add a Google Analytics site tag to each page of your +documentation. -### [sphinx-sitemap](https://sphinx-sitemap.readthedocs.io/en/latest/index.html) for search engine optimization +### [sphinx-sitemap](https://sphinx-sitemap.readthedocs.io/en/latest/index.html) for search engine optimization -While we are trying to move away from Google Analytics do -to compliance and privacy issues, search engine optimization +While we are trying to move away from Google Analytics do +to compliance and privacy issues, search engine optimization is still important. Google is the most popular search engine. -And if your documentation is search optimized, users are more +And if your documentation is search optimized, users are more likely to find your package! -If you are interested in optimizing your documentation for -search engines such as Google, you want a **sitemap.xml** file. -You can submit this sitemap to Google and it will index your -entire site. This over time can make the content on your site -more visible to others when they search. +If you are interested in optimizing your documentation for +search engines such as Google, you want a **sitemap.xml** file. +You can submit this sitemap to Google and it will index your +entire site. This over time can make the content on your site +more visible to others when they search. This extension is lightweight. @@ -38,9 +38,9 @@ It [requires that you to add it to your Sphinx `conf.py` extension list and site ### [sphinxext.opengraph](https://github.com/wpilibsuite/sphinxext-opengraph) -OpenGraph is an extension that allows you to add metadata to your documentation -content pages. [The OpenGraph protocol allows other websites to provide a -useful preview of the content on your page when shared](https://www.freecodecamp.org/news/what-is-open-graph-and-how-can-i-use-it-for-my-website/#what-is-open-graph). This is important -for when the pages in your documentation are shared on social -media sites like Twitter and Mastodon and even for shares on -tools like Slack and Discourse. +OpenGraph is an extension that allows you to add metadata to your documentation +content pages. [The OpenGraph protocol allows other websites to provide a +useful preview of the content on your page when shared](https://www.freecodecamp.org/news/what-is-open-graph-and-how-can-i-use-it-for-my-website/#what-is-open-graph). This is important +for when the pages in your documentation are shared on social +media sites like Twitter and Mastodon and even for shares on +tools like Slack and Discourse. diff --git a/documentation/index.md b/documentation/index.md index 3a5eb858..7c0ae6e6 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -1,14 +1,14 @@ # Documentation for your Open Source Python Package -```{important} -Please note that the tools discussed here are those that -we see commonly used in the community. As tools evolve we -will update this guide. If you are submitting a package for -pyOpenSci peer review and use other tools that are not listed -in our guide to build your package you can still submit for -review! The tools listed here are suggestions, not -requirements. Our requirements are focused on the -documentation content of your package. +```{important} +Please note that the tools discussed here are those that +we see commonly used in the community. As tools evolve we +will update this guide. If you are submitting a package for +pyOpenSci peer review and use other tools that are not listed +in our guide to build your package you can still submit for +review! The tools listed here are suggestions, not +requirements. Our requirements are focused on the +documentation content of your package. ``` - -## Documentation is critical for your Python package's success +## Documentation is critical for your Python package's success -Documentation is as important to the success of your Python open source package -as the code itself. +Documentation is as important to the success of your Python open source package +as the code itself. -Quality code is of course valuable as its how your package gets the tasks done. However, if users don't understand -how to use your package in their workflows, then they won't use it. +Quality code is of course valuable as its how your package gets the tasks done. However, if users don't understand +how to use your package in their workflows, then they won't use it. -Further, explicitly documenting how to contribute is important if you wish -to build a base of contributors to your package. +Further, explicitly documenting how to contribute is important if you wish +to build a base of contributors to your package. -## Two types of Python package users +## Two types of Python package users -The documentation that you write for your +The documentation that you write for your package should target two types of users: -### 1. Basic Tool Users +### 1. Basic Tool Users -Basic tool users are the people who will use your package code in their -Python workflows. They might be new(er) to Python and/or data science. Or -expert programmers. But they might not have a background in software +Basic tool users are the people who will use your package code in their +Python workflows. They might be new(er) to Python and/or data science. Or +expert programmers. But they might not have a background in software development. These users need to know: * How to install your package * How to install dependencies that your package requires * How to get started using the code base - * Information on how to cite your code / give you credit if they are using it + * Information on how to cite your code / give you credit if they are using it in a research application. - * Information on the license that your code uses so they know how they can + * Information on the license that your code uses so they know how they can or can't use the code in an operational setting. -### 2. Potential tool contributors +### 2. Potential tool contributors -The other subset of users are more experienced and/or more engaged -with your package. As such they are +The other subset of users are more experienced and/or more engaged +with your package. As such they are potential contributors. These users: * might have a software development background, * might also be able to contribute bug fixes to your package or updates to your documentation * might also just be users who will find spelling errors in your documentation, or bugs in your tutorials. -These users need all of the things that a basic user needs. But, they -also need to understand how you'd like for them to contribute to your +These users need all of the things that a basic user needs. But, they +also need to understand how you'd like for them to contribute to your package. These potential contributors need: * A development guide to help them understand the infrastructure used in your package repository. * Contributing guidelines that clarify the types of contributions that you welcome and how you'd prefer those contributions to be submitted. ```{important} -It's important to remember that the definition of what a contribution is can be -broad. A contribution could be something as simple as a bug report. Or fixing a -spelling issue in your documentation. Or it could be a code fix that includes a -new test that covers an edge-case that they discovered. +It's important to remember that the definition of what a contribution is can be +broad. A contribution could be something as simple as a bug report. Or fixing a +spelling issue in your documentation. Or it could be a code fix that includes a +new test that covers an edge-case that they discovered. ``` ## Documentation elements that pyOpenSci looks for reviewing a Python package -In the pyOpenSci open peer review, we look for -a documentation structure that supports both your tool users and potential -contributors. The files and elements that we look for specifically can be +In the pyOpenSci open peer review, we look for +a documentation structure that supports both your tool users and potential +contributors. The files and elements that we look for specifically can be found in our peer review check list (see link below). In this guide, we discuss each required element, and also discuss other elements -that you should consider in your package's documentation in more detail. +that you should consider in your package's documentation in more detail. @@ -111,15 +111,15 @@ that you should consider in your package's documentation in more detail. :class: sd-rounded-pill float-left View pyOpenSci peer review check list ``` - @@ -128,7 +128,7 @@ View pyOpenSci peer review check list name: directive-fig width: 80% alt: Image showing the files in the the MovingPandas GitHub repository. Files there include code of conduct.md, -Contributing.md, license.txt, readme.md. +Contributing.md, license.txt, readme.md. --- An example from the MovingPandas GitHub repository with all of the major files in it including CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md and a LICENSE.txt file. *(screen shot taken Nov 23 2022)* ``` @@ -137,13 +137,13 @@ An example from the MovingPandas GitHub repository with all of the major files i ## What's next in this Python package documentation section? -In this section of the pyOpenSci package guide, we will walk +In this section of the pyOpenSci package guide, we will walk you through best practices for setting up -documentation for your Python package. We will also suggest -tools that you can use to build your user-facing documentation website. +documentation for your Python package. We will also suggest +tools that you can use to build your user-facing documentation website. - - - diff --git a/documentation/repository-files/code-of-conduct-file.md b/documentation/repository-files/code-of-conduct-file.md index f3baa22d..fe270a4a 100644 --- a/documentation/repository-files/code-of-conduct-file.md +++ b/documentation/repository-files/code-of-conduct-file.md @@ -1,36 +1,36 @@ # The CODE_OF_CONDUCT.md file In Your Python Open Source Package ```{tip} -## Example Code of Conduct files +## Example Code of Conduct files * [SciPy Code of Conduct file - notice they included theirs in their documentation](https://docs.scipy.org/doc/scipy/dev/conduct/code_of_conduct.html) * [fatiando code of conduct file](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md) ``` -Your package should have a **CODE_OF_CONDUCT.md** file located -the root of the repository. Once you have people using your -package, you can consider the package itself as having a community -around it. Some of this community uses your tool. These users -may have questions or encounter challenges using your package. +Your package should have a **CODE_OF_CONDUCT.md** file located +the root of the repository. Once you have people using your +package, you can consider the package itself as having a community +around it. Some of this community uses your tool. These users +may have questions or encounter challenges using your package. -Others in the community might want to contribute to your tool. -They might fix bugs, update documentation and engage with the +Others in the community might want to contribute to your tool. +They might fix bugs, update documentation and engage with the maintainer team. ## Why you need a code of conduct In order to keep this community healthy and to protect yourself, -your mainatianer team and your users from unhealthy behavior, -it is important to have a [code of conduct](https://opensource.guide/code-of-conduct/). - -The code of conduct is important -as it establishes what you expect in terms of how users and -contributors interact with maintainers and each other. It also -establishes rules and expectations which can then be enforced -if need be to protect others from harmful and/or negative behaviors. - -If you are not comfortable -with creating your own code of conduct text, we encourage you to adopt the -code of conduct language used in the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). -[Many other communities](https://www.contributor-covenant.org/adopters/) have adopted this code of conduct as +your mainatianer team and your users from unhealthy behavior, +it is important to have a [code of conduct](https://opensource.guide/code-of-conduct/). + +The code of conduct is important +as it establishes what you expect in terms of how users and +contributors interact with maintainers and each other. It also +establishes rules and expectations which can then be enforced +if need be to protect others from harmful and/or negative behaviors. + +If you are not comfortable +with creating your own code of conduct text, we encourage you to adopt the +code of conduct language used in the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). +[Many other communities](https://www.contributor-covenant.org/adopters/) have adopted this code of conduct as their own. See the [Fatiando a Terra Geoscience Python community's example here.](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md) diff --git a/documentation/repository-files/contributing-file.md b/documentation/repository-files/contributing-file.md index e5aab7f5..2c1138c0 100644 --- a/documentation/repository-files/contributing-file.md +++ b/documentation/repository-files/contributing-file.md @@ -3,26 +3,23 @@ ## What a CONTRIBUTING.md file should contain ```{tip} -## Example contributing files +## Example contributing files * [pyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md) * [fatiando verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md) ``` -Your Python open source package should include a file called **CONTRIBUTING.md** located in the +Your Python open source package should include a file called **CONTRIBUTING.md** located in the root of your repository (with your **README.md** file). -The contributing file should include information about the types -of contributions that you welcome, and how you'd like to see -contributions happen. +The contributing file should include information about the types +of contributions that you welcome, and how you'd like to see +contributions happen. -This guide should also include information for someone +This guide should also include information for someone interested in asking questions, submitting issues or pull requests. It should have things like: -* Any guidelines that you have in place for users submitting issues, pull requests or asking questions. +* Any guidelines that you have in place for users submitting issues, pull requests or asking questions. * A link to your code of conduct -* A link to licensing information found in your README file. +* A link to licensing information found in your README file. * A link to a development guide if you have one - - - diff --git a/documentation/repository-files/development-guide.md b/documentation/repository-files/development-guide.md index b213c503..26d4166e 100644 --- a/documentation/repository-files/development-guide.md +++ b/documentation/repository-files/development-guide.md @@ -1,52 +1,52 @@ -# What the development guide for your Python package should contain +# What the development guide for your Python package should contain Ideally, your package should also have a development guide. This file may live in your package documentation and should be linked to from your CONTRIBUTING.md file (discussed above). -A development guide should clearly show +A development guide should clearly show technically proficient users how to: * Set up a development environment locally to work on your package -* Run the test suite +* Run the test suite * Build documentation locally The development guide should also have guidelines for: -* code standards including docstring style, code format and any specific code approaches that the package follows. +* code standards including docstring style, code format and any specific code approaches that the package follows. -It's also helpful to specify the types of tests you request if a contributor submits a new feature or a change to an existing feature that will not be covered by your existing test suite. +It's also helpful to specify the types of tests you request if a contributor submits a new feature or a change to an existing feature that will not be covered by your existing test suite. -If you have time to document it, it's also helpful to document your maintainer workflow and release processes. +If you have time to document it, it's also helpful to document your maintainer workflow and release processes. -### Why a development guide is important +### Why a development guide is important -It's valuable to have a development guide, in the +It's valuable to have a development guide, in the case that you wish to: * Onboard new maintainers. * Allow technically inclined contributors to make thoughtful and useful code based pull requests to your repository. -It also is important to pyOpenSci that the maintenance workflow is -documented in the case that we need to help you onboard new -maintainers in the future. +It also is important to pyOpenSci that the maintenance workflow is +documented in the case that we need to help you onboard new +maintainers in the future. ```{note} -A well thought out continuous integration setup in your repository +A well thought out continuous integration setup in your repository can allow users to skip building the package locally (especially if they are just updating text). -``` +``` ```{tip} -A development guide, while strongly recommended, is not a file that -pyOpenSci requires a package to have in order to be eligible for -review. Some maintainers may also opt to include the development information in their contributing guide. +A development guide, while strongly recommended, is not a file that +pyOpenSci requires a package to have in order to be eligible for +review. Some maintainers may also opt to include the development information in their contributing guide. ``` ```{tip} -[The Mozilla Science Lab website has a nice outline of things to consider when +[The Mozilla Science Lab website has a nice outline of things to consider when creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/) ``` - \ No newline at end of file +- **Better/Best:** Choose a license based on your needs and future use of package, plus explain your choice in your submission for review. --> diff --git a/documentation/repository-files/intro.md b/documentation/repository-files/intro.md index 40659e8f..3e82cf42 100644 --- a/documentation/repository-files/intro.md +++ b/documentation/repository-files/intro.md @@ -1,7 +1,7 @@ -# Documentation Files That Should be in your Python Package Repository +# Documentation Files That Should be in your Python Package Repository -In this section of the Python packaging guide, we review all of the files that -you should have in your Python package repository. Your Python package should, +In this section of the Python packaging guide, we review all of the files that +you should have in your Python package repository. Your Python package should, at a minimum have the following files: ```{toctree} @@ -15,11 +15,11 @@ Development Guide LICENSE files ``` -The files mentions above (README, Code of Conduct, license -file, etc) are used as a measure of package community health -on many online platforms. Below, you can see an example how Github -evaluates community health. This community health link is available for -all GitHub repositories. +The files mentions above (README, Code of Conduct, license +file, etc) are used as a measure of package community health +on many online platforms. Below, you can see an example how Github +evaluates community health. This community health link is available for +all GitHub repositories. ```{figure} /images/moving-pandas-python-package-github-community-standards.png --- @@ -30,9 +30,9 @@ alt: Image showing that the MovingPandas GitHub repository community health page GitHub community health looks for a readme file among other elements when it evaluates the community level health of your repository. This example is from the [MovingPandas GitHub repo](https://github.com/anitagraser/movingpandas/community) *(screen shot taken Nov 23 2022)* ``` -[Snyk](https://snyk.io/advisor/python) is another well-known company that -keeps tabs on package health. Below you can see a similar evaluation of files -in the Github repo as a measure of community health. +[Snyk](https://snyk.io/advisor/python) is another well-known company that +keeps tabs on package health. Below you can see a similar evaluation of files +in the Github repo as a measure of community health. ```{figure} /images/moving-pandas-python-package-snyk-health.png --- @@ -42,4 +42,3 @@ alt: Screenshot of the Snyk page for movingpandas. It shows that the repository --- Screenshot showing [SNYK](https://snyk.io/advisor/python/movingpandas) package health for moving pandas. Notice both platforms look for a README file. *(screen shot taken Nov 23 2022)* ``` - diff --git a/documentation/repository-files/license-files.md b/documentation/repository-files/license-files.md index 23c568f8..7abdfb8d 100644 --- a/documentation/repository-files/license-files.md +++ b/documentation/repository-files/license-files.md @@ -1,26 +1,26 @@ # Your repository should have a LICENSE.md file -The root of your GitHub repository should also have a LICENSE.txt file. +The root of your GitHub repository should also have a LICENSE.txt file. -To be reviewed by pyOpenSci your project should use an open source -software license that is approved -by the Open Software Initiative (OSI). OSI's website has a -[list of popular licenses](https://opensource.org/licenses). GitHub also has a -[handy tool](https://choosealicense.com/) for choosing a license. +To be reviewed by pyOpenSci your project should use an open source +software license that is approved +by the Open Software Initiative (OSI). OSI's website has a +[list of popular licenses](https://opensource.org/licenses). GitHub also has a +[handy tool](https://choosealicense.com/) for choosing a license. If you choose your license through GitHub, you can also automatically get a copy of the license file to add to your repository. ### Important: make sure that you closely follow the guidelines outlines by the License that you chose -Every license has different guidelines in terms of what code -you can use in your package and also how others can (or can not) use the code in your package. +Every license has different guidelines in terms of what code +you can use in your package and also how others can (or can not) use the code in your package. -If you borrow code from other tools or online sources, make -sure that the license for the code that you are using also complies -with the license that you selected for your package. +If you borrow code from other tools or online sources, make +sure that the license for the code that you are using also complies +with the license that you selected for your package. -```{note} -An example of code that would not comply with a BSD or MIT license would be any code copied from StackOverflow website. +```{note} +An example of code that would not comply with a BSD or MIT license would be any code copied from StackOverflow website. [Stack overflow users a Creative Commons Share Alike license.](https://stackoverflow.com/help/licensing) The sharealike license requires you to use the same sharealike license when you reuse any code from stackoverflow. Thus, if you use code from stack overflow in your package and have a MIT license applied to your package, you are violating stack overflow's license requirements! Proceed with caution here! ``` @@ -33,4 +33,4 @@ i think we need to better understand how this works before adding it... These files - we need to understand if that date releases auto populates or forces zenodo to modify it's citation. if it's not dynamic it could be problematic ---> \ No newline at end of file +--> diff --git a/documentation/repository-files/readme-file-best-practices.md b/documentation/repository-files/readme-file-best-practices.md index be8774a7..88c96081 100644 --- a/documentation/repository-files/readme-file-best-practices.md +++ b/documentation/repository-files/readme-file-best-practices.md @@ -1,50 +1,50 @@ # README File Guidelines and Resources -Your **README.md** file should be located in the root of your GitHub repository. -The **README.md** file is important as it is often the first thing that someone -sees before they install your package. +Your **README.md** file should be located in the root of your GitHub repository. +The **README.md** file is important as it is often the first thing that someone +sees before they install your package. The README.md file is the landing page of: * Your package as it appears on a repository site such as PyPI or Anaconda * Your package's GitHub repository -Your README.md file is also used as a measure of package and community +Your README.md file is also used as a measure of package and community health on sites such as: -* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/anitagraser/movingpandas/community) and [Snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas) +* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/anitagraser/movingpandas/community) and [Snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas) ```{figure} /images/pandera-python-package-readme-github.png --- name: directive-fig width: 80% -alt: README landing page screenshot for the Pandera package. It has the pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle: statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness. -Below that are a series of badges including CI tests passing, docs passing, version of pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that. +alt: README landing page screenshot for the Pandera package. It has the pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle: statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness. +Below that are a series of badges including CI tests passing, docs passing, version of pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that. Finally below the badges the text reads: Pandera provides a flexible and expressive API for performing data validation on dataframe-like objects to make data processing pipelines more readable and robust. --- Your GitHub repository landing page highlights the README.md file. Here you can see the README.md file for the pyOpenSci package [Pandera](https://github.com/unionai-oss/pandera). *(screen shot taken Nov 23 2022)* ``` -Thus, it is important that you spend some time up front creating a high quality +Thus, it is important that you spend some time up front creating a high quality **README.md** file for your Python package. ````{note} An editor or the editor in chief will ask you to revise your README file -before a review begins if it does not meet the criteria specified below. +before a review begins if it does not meet the criteria specified below. Please go through this list before submitting your package to pyOpenSci ``` -### pyOpenSci README checklist +### pyOpenSci README checklist -Your README file should have the following information: +Your README file should have the following information: - [ ] The name of the package -- [ ] Badges for the packages current published version, documentation and test suite build. (OPTIONAL: test coverage) +- [ ] Badges for the packages current published version, documentation and test suite build. (OPTIONAL: test coverage) - [ ] Easy-to-understand explanation (2-4 sentences) of what your tool does -- [ ] Context for how the tool fits into the broader ecosystem +- [ ] Context for how the tool fits into the broader ecosystem - [ ] If your library/package "wraps" around another package, link to the package that it is wrapping and any associated documentation. *(HINT: If you don't know what a wrapper is, this probably doesn't apply to you!)* -- [ ] A simple quick-start code example that a user can follow to provide a demonstration of what the package can do for them +- [ ] A simple quick-start code example that a user can follow to provide a demonstration of what the package can do for them - [ ] Links to your package's documentation / website. - [ ] A few descriptive links to any tutorials you've created for your package. ``` @@ -55,23 +55,23 @@ Your README file should have the following information: Your **README.md** file should contain the following things (listed from top to bottom): ### ✔️ Your package's name -Ideally your GitHub repository's name is also the name of your package. The more -self explanatory that name is, the better. +Ideally your GitHub repository's name is also the name of your package. The more +self explanatory that name is, the better. ### ✔️ Badges for current package version, continuous integration and test coverage -Badges are a useful way to draw attention to the quality of your project. Badges -assure users that your package is well-designed, tested, and maintained. They -are also a useful maintenance tool to evaluate if things are building properly. +Badges are a useful way to draw attention to the quality of your project. Badges +assure users that your package is well-designed, tested, and maintained. They +are also a useful maintenance tool to evaluate if things are building properly. A great example of this is adding a [Read the Docs status badge](https://docs.readthedocs.io/en/stable/badges.html) to your README.md file to quickly -see when the build on that site fails. +see when the build on that site fails. -It is common to provide a collection of badges towards the top of your +It is common to provide a collection of badges towards the top of your README file for others to quickly browse. Some badges that you might consider adding to your README file include: -* Current version of the package on PyPI / Anaconda Cloud +* Current version of the package on PyPI / Anaconda Cloud Example: [![PyPI version shields.io](https://img.shields.io/pypi/v/pandera.svg)](https://pypi.org/project/pandera/) @@ -82,8 +82,8 @@ Example: [![PyPI version shields.io](https://img.shields.io/pypi/v/pandera.svg)] * DOI (for citation) Example: [![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582) ```{tip} -Once you package is accepted to pyOpenSci, we will provide you with -a badge to add to your repository that shows that it has been reviewed. +Once you package is accepted to pyOpenSci, we will provide you with +a badge to add to your repository that shows that it has been reviewed. [![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/12) ``` @@ -93,84 +93,84 @@ a badge to add to your repository that shows that it has been reviewed. Beware of the overuse of badges! There is such a thing as too much of a good thing (which can overload a potential user!). ``` -### ✔️ A short, easy-to-understand description of what your package does +### ✔️ A short, easy-to-understand description of what your package does -At the top of your README file you should have a short, easy-to-understand, 1-3 -sentence description of what your package does. This section should clearly -state your goals for the package. The language in this description should use -less technical terms so that a variety of users with varying scientific (and -development) backgrounds can understand it. +At the top of your README file you should have a short, easy-to-understand, 1-3 +sentence description of what your package does. This section should clearly +state your goals for the package. The language in this description should use +less technical terms so that a variety of users with varying scientific (and +development) backgrounds can understand it. In this description, it's useful to let users know how your package fits within -the broader scientific Python package ecosystem. If there are other similar packages -or complementary package mentions them here in 1-2 sentences. +the broader scientific Python package ecosystem. If there are other similar packages +or complementary package mentions them here in 1-2 sentences. ```{tip} -Consider writing for a high school level (or equivalent) level. This -level of writing is often considered an appropriate level for scientific content that -serves a variety of users with varying backgrounds. +Consider writing for a high school level (or equivalent) level. This +level of writing is often considered an appropriate level for scientific content that +serves a variety of users with varying backgrounds. -The goal of this description is to maximize accessibility of your **README** +The goal of this description is to maximize accessibility of your **README** file. ``` ### ✔️ Installation instructions -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. +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 -Add any additional setup required such as authentication tokens, to -get started using your package. If setup is complex, consider linking to an +Add any additional setup required such as authentication tokens, to +get started using your package. If setup is complex, consider linking to an installation page in your online documentation here rather than over complicating -your README file. +your README file. ### ✔️ Brief demonstration of how to use the package -This description ideally includes a brief, quick start code -example that shows a user how to get started using your package. +This description ideally includes a brief, quick start code +example that shows a user how to get started using your package. ### ✔️ Descriptive links to package documentation, short tutorials Include descriptive links to: -* The package's documentation page. -* Short tutorials that demonstrate application of your package. +* The package's documentation page. +* Short tutorials that demonstrate application of your package. ```{tip} ### Too Much Of A Good Thing -Try to avoid including several tutorials in the README.md file itself. This too will overwhelm the user with information. +Try to avoid including several tutorials in the README.md file itself. This too will overwhelm the user with information. -A short quick-start code example that shows someone how to use your package -is plenty of content for the README file. All other tutorials and -documentation -should be presented as descriptive links. +A short quick-start code example that shows someone how to use your package +is plenty of content for the README file. All other tutorials and +documentation +should be presented as descriptive links. ``` -### ✔️ A Community Section with Links to Contributing Guide, Code of Conduct +### ✔️ A Community Section with Links to Contributing Guide, Code of Conduct Use your README.md file to direct users to more information on: -* Contributing to your package -* Development setup for more advanced technical contributors +* Contributing to your package +* Development setup for more advanced technical contributors * Your code of conduct * Licensing information -All of the above files are important for building community around your +All of the above files are important for building community around your project. ### ✔️ Citation information -Finally be sure to include instructions on how to cite your package. -Citation should include the DOI that you want used when citing your package, -and any language that you'd like to see associated with the citation. +Finally be sure to include instructions on how to cite your package. +Citation should include the DOI that you want used when citing your package, +and any language that you'd like to see associated with the citation. ```{tip} -### README Resources +### README Resources -Below are some resources on creating great README.md files that you +Below are some resources on creating great README.md files that you might find helpful. * [How to Write a Great README - Bane Sullivan](https://github.com/banesullivan/README) diff --git a/documentation/write-user-documentation/create-package-tutorials.md b/documentation/write-user-documentation/create-package-tutorials.md index 27e389c3..108ec4d9 100644 --- a/documentation/write-user-documentation/create-package-tutorials.md +++ b/documentation/write-user-documentation/create-package-tutorials.md @@ -1,43 +1,43 @@ -# Create tutorials in your Python package documentation +# Create tutorials in your Python package documentation - -Your package should have tutorials that make it easy for a user -to get started using your package. Ideally, those tutorials -also can be run from start to finish providing a second set of -checks (on top of your test suite) to your package's code base. +Your package should have tutorials that make it easy for a user +to get started using your package. Ideally, those tutorials +also can be run from start to finish providing a second set of +checks (on top of your test suite) to your package's code base. In the [documentation tools page](python-package-documentation-tools) we talk about two Sphinx extensions (`sphinx-gallery` and `nbsphinx`) -that allow you to create reproducible tutorials that are run -when your Sphinx documentation builds. +that allow you to create reproducible tutorials that are run +when your Sphinx documentation builds. ## Create Python package tutorials that run when you build your docs -Adding well constructed tutorials to your package will make it easier for someone -new to begin using your package. +Adding well constructed tutorials to your package will make it easier for someone +new to begin using your package. There are two Sphinx tools that make it easy to add tutorials to your package: -* [Sphinx Gallery](https://sphinx-gallery.github.io/stable/index.html) and +* [Sphinx Gallery](https://sphinx-gallery.github.io/stable/index.html) and * [NbSphinx](https://nbsphinx.readthedocs.io/en/latest/) Both of these tools act as Sphinx extensions and: * Support creating a gallery type page in your Sphinx documentation where users can explore tutorials via thumbnails. -* Run the code in your tutorials adding another level of "testing" for your package as used. +* Run the code in your tutorials adding another level of "testing" for your package as used. * Render your tutorials with Python code and plot outputs -### [sphinx gallery:](https://sphinx-gallery.github.io/stable/index.html) +### [sphinx gallery:](https://sphinx-gallery.github.io/stable/index.html) -If you prefer to write your tutorials using Python **.py** scripts, you -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: +If you prefer to write your tutorials using Python **.py** scripts, you +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. 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. 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. 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 @@ -48,7 +48,7 @@ width: 80% alt: Image showing the gallery output provided by sphinx-gallery where each tutorial is in a grid and the tutorial thumbnails are created from a graphic in the tutorial. --- `sphinx-gallery` makes it easy to create a user-friendly tutorial gallery. -Each tutorial has a download link where the user can download a **.py** file or a Jupyter Notebook. And it renders the tutorials in a user-friendly grid. +Each tutorial has a download link where the user can download a **.py** file or a Jupyter Notebook. And it renders the tutorials in a user-friendly grid. ``` Below you can see what a tutorial looks like created with sphinx-gallery. @@ -57,57 +57,57 @@ Below you can see what a tutorial looks like created with sphinx-gallery. --- name: directive-fig width: 80% -alt: Image showing ta single tutorial from Sphinx gallery. The tutorial shows a simple matplotlib created plot and associated code. +alt: Image showing ta single tutorial from Sphinx gallery. The tutorial shows a simple matplotlib created plot and associated code. --- -`sphinx-gallery` tutorials by default include download links for both the -python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bottom. +`sphinx-gallery` tutorials by default include download links for both the +python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bottom. ``` -### Sphinx Gallery benefits +### Sphinx Gallery benefits * easy-to-download notebook and .py outputs for each tutorials -* .py files are easy to work with in the GitHub pull request environment. +* .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) -#### Sphinx gallery challenges +#### Sphinx gallery challenges -The downsides of using Sphinx gallery include: +The downsides of using Sphinx gallery include: -* the **.py** files can be finicky to configure, particularly if you have matplotlib plot outputs. +* 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_` -at the beginning. +For example: To make 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 +* 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 +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 +```bash +$ docs % make html Sphinx-Gallery successfully executed 2 out of 2 files ``` -File directory structure: +File directory structure: ```bash tutorials/ index.rst # landing page for your gallery - plot_tutorial.py # a tutorial + plot_tutorial.py # a tutorial plot_tutorial-2.py # a tutorial that produces a plot output _build/ - build_examples/ # This is where the downloadable tutorial files live + build_examples/ # This is where the downloadable tutorial files live plot_sample-1.ipynb plot_sample-1.py ... - html/ + html/ built_examples/ # You can specify this dir name in gallery settings - index.html - plot_sample-1.html - plot_sample.html - sg_execution_times.html # in case you want to see build times for each tutorial + index.html + plot_sample-1.html + plot_sample.html + sg_execution_times.html # in case you want to see build times for each tutorial ``` @@ -116,9 +116,9 @@ _build/ If you prefer to use Jupyter Notebooks to create tutorials you can use nbsphinx. nbsphinx operates similarly to Sphinx gallery in that: -* It runs your notebooks and produces outputs in the rendered tutorials +* It runs your notebooks and produces outputs in the rendered tutorials -* Pro/con By default it does not support downloading of **.py** and **.ipynb** files. However you can add a [link to the notebook at the top of the page with +* Pro/con By default it does not support downloading of **.py** and **.ipynb** files. However you can add a [link to the notebook at the top of the page with some additional conf.py settings (see: epilog settings)](https://nbsphinx.readthedocs.io/en/0.8.10/prolog-and-epilog.html) @@ -126,11 +126,11 @@ some additional conf.py settings (see: epilog settings)](https://nbsphinx.readth --- name: directive-fig width: 80% -alt: Image showing the gallery output provided by nbsphinx using the sphinx-gallery front end interface. +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 -elements in a single column. +`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 +elements in a single column. ``` ```bash @@ -141,16 +141,14 @@ tutorials/ # This shows you what the build directory looks like when you build with sphinx-build _build/ html/ - # Notice that nbsphinx runs each notebook and produces an - # html file with all of the outputs of your code - # you can link to the notebook in your docs by modifying + # Notice that nbsphinx runs each notebook and produces an + # html file with all of the outputs of your code + # you can link to the notebook in your docs by modifying # the nbsphinx build - we will cover this in a separate tutorial series focused onPythonpackaging! - tutorials/ + tutorials/ index.html - index.md - plot_sample-2.html + index.md + plot_sample-2.html plot_sample-2.ipynb ... -``` - - +``` diff --git a/documentation/write-user-documentation/document-your-code-api-docstrings.md b/documentation/write-user-documentation/document-your-code-api-docstrings.md index a68e235d..522d1923 100644 --- a/documentation/write-user-documentation/document-your-code-api-docstrings.md +++ b/documentation/write-user-documentation/document-your-code-api-docstrings.md @@ -1,26 +1,26 @@ # Document the code in your package's API using docstrings ## What is an API? -API stands for **A**pplied **P**rogramming **I**nterface. When -discussed in the context of a (Python) package, the API refers to -the functions, methods and classes that a package maintainer creates for users. +API stands for **A**pplied **P**rogramming **I**nterface. When +discussed in the context of a (Python) package, the API refers to +the functions, methods and classes that a package maintainer creates for users. A simple example of a package API element: -For instance, a package might have a function called `add_numbers()` -that adds up a bunch of numbers. To add up numbers, you as the user -simply call `add_numbers(1,2,3)` and the package function calculates the value and returns `6`. By calling the `add_numbers` function, you are -using the package's API. +For instance, a package might have a function called `add_numbers()` +that adds up a bunch of numbers. To add up numbers, you as the user +simply call `add_numbers(1,2,3)` and the package function calculates the value and returns `6`. By calling the `add_numbers` function, you are +using the package's API. -Package APIs consist of functions and/or classes, methods and attributes that create a user interface (known as the API). +Package APIs consist of functions and/or classes, methods and attributes that create a user interface (known as the API). -## What is a docstring and how does it relate to documentation? -In Python a docstring refers to text in a function, method or class +## What is a docstring and how does it relate to documentation? +In Python a docstring refers to text in a function, method or class that describes what the function does and its inputs and outputs. Python programmers usually refer to the inputs to functions as ["parameters"](https://docs.python.org/3/glossary.html#term-parameter) or ["arguments"](https://docs.python.org/3/faq/programming.html#faq-argument-vs-parameter), and the outputs are often called "return values" The docstring is thus important for: -* When you call `help()` in Python, for example, `help(add_numbers)`, the text of the function's docstring is printed. The docstring thus helps a user better understand how to applying the function more effectively to their workflow. -* When you build your package's documentation, the docstrings can be also used to automagically create full API documentation that provides a clean view of all its functions, methods, attributes, and classes. +* When you call `help()` in Python, for example, `help(add_numbers)`, the text of the function's docstring is printed. The docstring thus helps a user better understand how to applying the function more effectively to their workflow. +* When you build your package's documentation, the docstrings can be also used to automagically create full API documentation that provides a clean view of all its functions, methods, attributes, and classes. ```{tip} Example API Documentation for all functions, methods, attributes and classes in a package. @@ -28,54 +28,54 @@ Example API Documentation for all functions, methods, attributes and classes in * [You can further dig down to see what a specific function does within the package by clicking on an API element](https://www.fatiando.org/verde/latest/api/generated/verde.grid_coordinates.html#verde.grid_coordinates) ``` -## Python package API documentation +## Python package API documentation -If you have a descriptive docstring for every user-facing -class, method, attribute and/or function in your package (*within reason*), then your package's API is considered well-documented. +If you have a descriptive docstring for every user-facing +class, method, attribute and/or function in your package (*within reason*), then your package's API is considered well-documented. -In Python, this means that you need to add a docstring for -every user-facing +In Python, this means that you need to add a docstring for +every user-facing class, method, attribute and/or function in your package (*within reason*) that: -* Explains what the function, method, attribute or class does +* Explains what the function, method, attribute or class does * Defines the `type` inputs and outputs (ie. `string`, `int`, `np.array`) * Explains the expected output `return` of the object, method or function. ### Three Python docstring formats and why we like NumPy style -There are several Python docstring formats that you can chose to use when documenting +There are several Python docstring formats that you can chose to use when documenting your package including: * [NumPy-style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) -* [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) -* [reST style](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) +* [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) +* [reST style](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) -We suggest using [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) for your +We suggest using [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) for your Python documentation because: -* NumPy style docstrings are core to the scientific Python ecosystem and defined in the [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html). Thus you will find them widely used there. +* NumPy style docstrings are core to the scientific Python ecosystem and defined in the [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html). Thus you will find them widely used there. * The Numpy style docstring is simplified and thus easier-to-read both in the code and when calling `help()` in Python. In contrast, some feel that reST style docstrings is harder to quickly scan, and can take up more lines of code in modules. ```{tip} -If you are using NumPy style docstrings, be sure to include the [sphinx napoleon -extension](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) in your documentation `conf.py` file. This extension allows Sphinx -to properly read and format NumPy format docstrings. +If you are using NumPy style docstrings, be sure to include the [sphinx napoleon +extension](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) in your documentation `conf.py` file. This extension allows Sphinx +to properly read and format NumPy format docstrings. ``` -### Docstring examples Better and Best +### Docstring examples Better and Best -Below is a good example of a well documented function. Notice that this -function's docstring describes the function's inputs and the function's output -(or return value). The initial description of the function is short (one line). -Following that single line description there is a slightly longer description of +Below is a good example of a well documented function. Notice that this +function's docstring describes the function's inputs and the function's output +(or return value). The initial description of the function is short (one line). +Following that single line description there is a slightly longer description of what the function does (2 to 3 sentences). The return of the function is also -specified. +specified. ```Python def extent_to_json(ext_obj): """Convert bounds to a shapely geojson like spatial object. - + This format is what shapely uses. The output object can be used to crop a raster image. @@ -99,13 +99,13 @@ def extent_to_json(ext_obj): (docstring_best_practice)= ### Best: a docstring with example use of the function -This example contains an example of using the function that is also tested in +This example contains an example of using the function that is also tested in sphinx using [doctest](https://docs.python.org/3/library/doctest.html). ```Python def extent_to_json(ext_obj): """Convert bounds to a shapely geojson like spatial object. - + This format is what shapely uses. The output object can be used to crop a raster image. @@ -122,7 +122,7 @@ def extent_to_json(ext_obj): for the extent A GeoJSON style dictionary of corner coordinates representing the spatial extent of the provided spatial object. - + Example ------- Convert a `geopandas.GeoDataFrame` to an extent dictionary: @@ -150,55 +150,55 @@ def extent_to_json(ext_obj): name: directive-fig width: 80% --- -Using the above NumPy format docstring in sphinx, the autodoc extension will -create the about documentation section for the `extent_to_json` function. The -output of the `es.extent_to_json(rmnp)` command can even be tested using -doctest adding another quality check to your package. +Using the above NumPy format docstring in sphinx, the autodoc extension will +create the about documentation section for the `extent_to_json` function. The +output of the `es.extent_to_json(rmnp)` command can even be tested using +doctest adding another quality check to your package. ``` ## Using doctest to run docstring examples in your package's methods and functions - -Above, we provided some examples of good, better, best docstring formats. If you are using Sphinx to create your docs, you can add the [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) extension to your Sphinx build. Doctest provides an additiona; check for docstrings with example code in them. -Doctest runs the example code in your docstring `Examples` checking +Above, we provided some examples of good, better, best docstring formats. If you are using Sphinx to create your docs, you can add the [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) extension to your Sphinx build. Doctest provides an additional; check for docstrings with example code in them. +Doctest runs the example code in your docstring `Examples` checking that the expected output is correct. Similar to running -tutorials in your documentation, `doctest` can be a useful step that +tutorials in your documentation, `doctest` can be a useful step that assures that your package's code (API) runs as you expect it to. -```{note} -It's important to keep in mind that examples in your docstrings -help users using your package. Running `doctest` on those examples provides a -check of your package's API. doctest ensures that the functions and methods in your package -run as you expect them to. Neither of these items replace a separate, -stand-alone test suite that is designed to test your package's core functionality -across operating systems and Python versions. +```{note} +It's important to keep in mind that examples in your docstrings +help users using your package. Running `doctest` on those examples provides a +check of your package's API. doctest ensures that the functions and methods in your package +run as you expect them to. Neither of these items replace a separate, +stand-alone test suite that is designed to test your package's core functionality +across operating systems and Python versions. ``` -Below is an example of a docstring with an example. -doctest will run the example below and test that if you provide -`add_me` with the values 1 and 3 it will return 4. +Below is an example of a docstring with an example. +doctest will run the example below and test that if you provide +`add_me` with the values 1 and 3 it will return 4. ```python def add_me(aNum, aNum2): - """A function that prints a number that it is provided. - + """A function that prints a number that it is provided. + Parameters ---------- aNum : int An integer value to be printed - - Returns + + Returns ------- Prints the integer that you provide the function. - + """ return aNum + aNum2 Examples -------- -Below you can see how the `print_me` function will print a number that +Below you can see how the `print_me` function will print a number that you provide it. >>> add_me(1+3) diff --git a/documentation/write-user-documentation/get-started.md b/documentation/write-user-documentation/get-started.md index f65f9f15..aa093193 100644 --- a/documentation/write-user-documentation/get-started.md +++ b/documentation/write-user-documentation/get-started.md @@ -1,75 +1,75 @@ -# Create User Facing Documentation for your Python Package +# Create User Facing Documentation for your Python Package -## Core components of user-facing Python package documentation +## Core components of user-facing Python package documentation Below we break documentation into two broad types. -**User-facing documentation **refers to documentation that describes the way the -tools within a package is broadly used in workflows. **API documentation, documentation of your functions, classes and methods in your code,** is written -at a more granular level. It is documentation for each specific function, class, -method or attribute that a user can use in the package. this is the documentation -that a user sees when they type `help(function-name)`. +**User-facing documentation **refers to documentation that describes the way the +tools within a package is broadly used in workflows. **API documentation, documentation of your functions, classes and methods in your code,** is written +at a more granular level. It is documentation for each specific function, class, +method or attribute that a user can use in the package. this is the documentation +that a user sees when they type `help(function-name)`. -Your user-facing documentation for your Python package should include several -core components. +Your user-facing documentation for your Python package should include several +core components. * **Documentation Website:** This refers to easy-to-read documentation that helps someone use your package. This documentation should help users both install and use your package. -* **Short Tutorials:** Your user-facing documentation should also include [**short tutorials** that show case core features of your package](create-package-tutorials). -* **Package Code / API documentation:** You package's functions, methods, attributes and classes (the API) should also be documented. API documentation can be generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your -code. Ideally, you have docstrings for all user-facing functions, methods and classes in +* **Short Tutorials:** Your user-facing documentation should also include [**short tutorials** that show case core features of your package](create-package-tutorials). +* **Package Code / API documentation:** You package's functions, methods, attributes and classes (the API) should also be documented. API documentation can be generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your +code. Ideally, you have docstrings for all user-facing functions, methods and classes in your Python package. [We discuss code documentation and docstrings in greater detail here.](document-your-code-api-docstrings) -### Write usable documentation +### Write usable documentation -User-facing documentation should be published on a -easy-to-navigate website. The documentation should be written keeping in mind that users may not be developers or expert-level programmers. Rather, the language -that you use in your documentation should not be -highly technical. +User-facing documentation should be published on a +easy-to-navigate website. The documentation should be written keeping in mind that users may not be developers or expert-level programmers. Rather, the language +that you use in your documentation should not be +highly technical. -To make the language of your documentation more accessible -to a broader audience: +To make the language of your documentation more accessible +to a broader audience: * Whenever possible, define technical terms and jargon. -* Consider writing instructions for a high-school level reader. +* Consider writing instructions for a high-school level reader. * Include step-by-step code examples, tutorials or vignettes that support getting started using your package. ## Four elements of a good open source documentation landing page -To make it easy for users to find what they need quickly, -consider adding quick links on your packages landing +To make it easy for users to find what they need quickly, +consider adding quick links on your packages landing page to the following elements: -* **Getting started:** This section should provide the user with a quick start for installing your package. A small example of how to use the package is good to have here as well. Or you can link to useful tutorials in the get started section. +* **Getting started:** This section should provide the user with a quick start for installing your package. A small example of how to use the package is good to have here as well. Or you can link to useful tutorials in the get started section. * **About:** Describe your project, stating its goals and its functionality. -* **Community:** Instructions for how to help and/or get involved. This might include links to your issues (if that is where you let users ask questions) or the discussion part of your GitHub repo. This section might include a development guide for those who might contribute to your package. -* **API Documentation:** This is the detailed project documentation. Here you store documentation for your package's api including all user-facing functions, methods classes. And any additional high level discussion that will help people use your package. +* **Community:** Instructions for how to help and/or get involved. This might include links to your issues (if that is where you let users ask questions) or the discussion part of your GitHub repo. This section might include a development guide for those who might contribute to your package. +* **API Documentation:** This is the detailed project documentation. Here you store documentation for your package's api including all user-facing functions, methods classes. And any additional high level discussion that will help people use your package. ```{figure} /images/geopandas-documentation-landing-page.png --- name: directive-fig width: 80% -alt: Image showing the landing page for GeoPandas documentation which has 4 sections including Getting started, Documentation, About GeoPandas, Community. +alt: Image showing the landing page for GeoPandas documentation which has 4 sections including Getting started, Documentation, About GeoPandas, Community. --- The documentation landing page of GeoPandas, a spatial Python library, has the 4 element specified above. Notice that the landing page is simple and directs users to each element using a Sphinx card. ``` -NOTE: in many cases you can include your **README** file and your **CONTRIBUTING** files +NOTE: in many cases you can include your **README** file and your **CONTRIBUTING** files in your documentation given those files may have some of the components listed above. `````{tip} You can include files in Sphinx using the include directive. -Below is an example of doing this using `myst` syntax. +Below is an example of doing this using `myst` syntax. ```` ```{include} ../README.md ``` diff --git a/documentation/write-user-documentation/intro.md b/documentation/write-user-documentation/intro.md index 72c9ca1e..d84e8107 100644 --- a/documentation/write-user-documentation/intro.md +++ b/documentation/write-user-documentation/intro.md @@ -1,20 +1,20 @@ -# Writing user-facing documentation for your Python package +# Writing user-facing documentation for your Python package -This section walks you through best practices for with writing +This section walks you through best practices for with writing documentation for your Python package. We talk about the elements that you should consider adding to your documentation, -the different types of users who might read your documentation and how to +the different types of users who might read your documentation and how to create tutorials for your package. -Here we also cover sphinx extensions that you can user to make documentation +Here we also cover sphinx extensions that you can user to make documentation easier such as: -* autodoc to automagically populate documentation for your code's functions, +* autodoc to automagically populate documentation for your code's functions, classes, methods and attributes (API documentation) and -* sphinx gallery for tutorials. +* sphinx gallery for tutorials. -## User-facing documentation sections +## User-facing documentation sections ```{toctree} :maxdepth: 2 @@ -24,4 +24,3 @@ Create Your Docs Document Your Code (API) Create Package Tutorials ``` - diff --git a/index.md b/index.md index d89f28d3..be7e3894 100644 --- a/index.md +++ b/index.md @@ -1,12 +1,12 @@ -# pyOpenSci Python Open Source Package Development Guide +# pyOpenSci Python Open Source Package Development Guide - -## Welcome, Python open source enthusiast! +## Welcome, Python open source enthusiast! -Here you will find guidelines for what we look for in your scientific -Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and documentation. +Here you will find guidelines for what we look for in your scientific +Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and documentation. ::::{grid} 2 :reverse: @@ -15,7 +15,7 @@ Python package when reviewing. You will also find best practice recommendations :columns: 4 :class: sd-m-auto -::: +::: :::{grid-item} :columns: 8 @@ -52,10 +52,10 @@ Learn about our open peer review process ✨ Documentation Criteria & Recommendations ✨ ^^^ -Learn more about the best practices for Python package -documentation and also some of the tools for creating -documentation that are -commonly used in the scientific Python community. +Learn more about the best practices for Python package +documentation and also some of the tools for creating +documentation that are +commonly used in the scientific Python community. ::: :::{grid-item-card} @@ -65,9 +65,9 @@ commonly used in the scientific Python community. ✨ Package Structure & Code ✨ ^^^ -Under Construction - Coming Spring 2023! -Learn more about standards for packaging structure and -builds in the scientific Python community. +Under Construction - Coming Spring 2023! +Learn more about standards for packaging structure and +builds in the scientific Python community. ::: :::{grid-item-card} @@ -77,35 +77,35 @@ builds in the scientific Python community. ✨ Want to contribute? ✨ ^^^ -We welcome contributions to this guide. Learn more about how you can +We welcome contributions to this guide. Learn more about how you can contribute. ::: :::: -## Who this guidebook is for -We assume that you are here because you are: +## Who this guidebook is for +We assume that you are here because you are: 1. Considering submitting a package to pyOpenSci and want to understand what we are looking for when we review your package -2. Looking for guidance on creating a Python package. +2. Looking for guidance on creating a Python package. 3. Looking for resources associated with Python packaging. -Well, friend, you've come to the right place! +Well, friend, you've come to the right place! -## What you will find in this guidebook +## What you will find in this guidebook -This guidebook contains: +This guidebook contains: * Explanation for "Good enough" minimum requirements associated with being reviewed by pyOpenSci * Explanation of better and best practices in case you want to set the bar higher for your package (which we hope you will)! -* A curated list of resources to help you get your package into documented, usable and tested shape. +* A curated list of resources to help you get your package into documented, usable and tested shape. -## Where this guide is headed +## Where this guide is headed -Most of the sections in this guide will ultimately include Good/Better/Best recommendations for Python open source software packaging. +Most of the sections in this guide will ultimately include Good/Better/Best recommendations for Python open source software packaging. Good meets the requirements. Going beyond the minimum can make package maintenance easier-to-use for new users, easier-to contribute for new contributors and easier-to-maintain for you. -This guide is now a work in progress. If you have ideas of things you'd like +This guide is now a work in progress. If you have ideas of things you'd like to see here, [we invite you to open an issue on GitHub that details any changes or additions that you'd like to see.](https://github.com/pyOpenSci/python-package-guide/issues). @@ -141,15 +141,15 @@ Intro - -```{button-link} https://www.pyopensci.org/peer-review-guide/software-peer-review-guide/editor-in-chief-guide.html#editor-checklist-template +```{button-link} https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template :color: primary :class: sd-rounded-pill float-left View pyOpenSci peer review check list