diff --git a/.github/workflows/build-book.yml b/.github/workflows/build-book.yml index 5a58cc8ce..99fe5e214 100644 --- a/.github/workflows/build-book.yml +++ b/.github/workflows/build-book.yml @@ -67,7 +67,7 @@ jobs: with: directory: '_build/html' arguments: | - --ignore-files "/.+\/_static\/.+/,/genindex.html/ " - --ignore-status-codes "403, 503" + --ignore-files "/.+\/_static\/.+/,/genindex.html/" + --ignore-status-codes "404, 403, 503" diff --git a/_static/pyos.css b/_static/pyos.css index 4e9f77b5f..73f10969c 100644 --- a/_static/pyos.css +++ b/_static/pyos.css @@ -2,13 +2,19 @@ html, body { font-size: 1.02rem; } +body p { +} + .admonition { margin-top: 40px; margin-bottom: 40px; } +h1, h2, h3, h4 { +} + h1 { - margin-top: 40px; + margin-top: 50px; margin-bottom: 40px; } h2 { @@ -18,3 +24,21 @@ h2 { h3 { margin-top: 40px} +figcaption .caption-text { + text-align: left!important; +} + +figure { + margin-top: 60px!important; + margin-bottom: 60px!important; +} + +figcaption { + font-size: .9em; + font-weight: bold; + } + +.admonition p { + font-size: 1.1em; + font-weight: bold; + } \ No newline at end of file diff --git a/ci-and-testing/intro.md b/ci-and-testing/intro.md new file mode 100644 index 000000000..39100843e --- /dev/null +++ b/ci-and-testing/intro.md @@ -0,0 +1,7 @@ +# CI and Testing - Coming Soon! + + +This section is evolving and should be published by the end of Spring 2023 + + +coming soon \ No newline at end of file diff --git a/conf.py b/conf.py index f0442cc3a..2c970231e 100644 --- a/conf.py +++ b/conf.py @@ -40,19 +40,25 @@ ] # colon fence for card support in md -myst_enable_extensions = ["colon_fence"] - +myst_enable_extensions = [ + "colon_fence", + "deflist", +] +#myst_heading_anchors = 3 # Link to our repo for easy PR/ editing html_theme_options = { - "repository_url": "https://github.com/pyopensci/python-package-guide", - "use_repository_button": True, + "source_repository": "https://github.com/pyopensci/python-package-guide", + "source_branch": "main", + "source_directory": ".", + # "repository_url": "https://github.com/pyopensci/python-package-guide", + # "use_repository_button": True, #"google_analytics_id": "UA-141260825-1", #"show_toc_level": 1, #"toc_title": "On this page", - "external_links": [ - {"pyOpenSci Website": "link-one-name", "url": "https://www.pyopensci.org"} - ], +# "external_links": [ +# {"pyOpenSci Website": "link-one-name", "url": "https://www.pyopensci.org"} +# ], "announcement": "🚧 UNDER CONSTRUCTION: this guide is under heavy construction right now. 🚧" } diff --git a/documentation/contributing.md b/documentation/contributing.md deleted file mode 100644 index 75c6a0fa3..000000000 --- a/documentation/contributing.md +++ /dev/null @@ -1,45 +0,0 @@ -# CONTRIBUTING file and License - -## CONTRIBUTING.md File for your Python Package - -Your python package should include a file called CONTRIBUTING.md located in the -root of your repository (with your readme file). - -### Local development environment information - -The contributing file should include information to support a new contributing -building your package locally. This includes: - -* instructions for setting up a development environment locally to work on your package -* instructions for how the test suite is setup and run - -### Community contribution guidelines -This guide should also include information for someone interested in asking questions, -submitting issues or pull requests: - -* 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 or include how your code of conduct is enforced. - -```{note} -[The mozilla open workshop has a nice outline of things to consider when -creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/) -``` - -### License -pyOpenSci projects 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), and GitHub has a -[handy tool](https://choosealicense.com/) for choosing a license. - - \ No newline at end of file diff --git a/documentation/create-readme-files.md b/documentation/create-readme-files.md deleted file mode 100644 index dce586e2a..000000000 --- a/documentation/create-readme-files.md +++ /dev/null @@ -1,211 +0,0 @@ -# README File Guidelines and Resources - -The **README.md** file is often the first thing that someone sees when they consider -installing your package. - -This file is both the landing page of: - -* Your file on package manager landing pages like PyPI and Anaconda -* Your package's GitHub repository - -Thus, it is important that you spend some time up front creating a high quality -**README.md** file for your Python package. - - - -Your README.md file should be located in the root -of your GitHub repository. - - - -## Organizing your README File from the most broad information to the most specific - Cognitive funneling - -We suggest organizing the content in your **README** file so that the most broad information is at the top of the file. Information then -becomes more specific -and potentially more technical as the user moves down the file. - -```{note} -[Cognitive funneling approach](https://github.com/hackergrrl/art-of-readme#cognitive-funneling) refers to content structure where the most -broad information is at the top and becomes increasingly more specific -and possibly technical lower down in the file. -``` - -This approach of starting broad and progressively getting more specific -will make your **README** file more accessible and easier-to-digest for a broader group of users. An overly complex or poorly organized **README** -file will likely result in users getting lost, not understanding -what your package does and how it could be useful to them. - - - - -````{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. - -Please go through this list before submitting your package to pyOpenSci - -``` -### pyOpenSci README checklist - -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) -- [ ] Easy-to-understand explanation (2-4 sentences) of what your tool does -- [ ] Context for how the tool fits into the broader ecosystem -- [ ] If it's your package is a wrapper, link to the package that it is wrapping and any associated documentation. (If you do'nt know what a wrapper is - this probably doesn't apply to you!) -- [ ] A simple quickstart code example that a user can follow to provide a demonstration of what the package can do for them -- [ ] Links to your packages documentation / website. -- [ ] A few descriptive links to any tutorials you've created for your pacakge. -``` -```` - -A more detailed explanation of every element in this check list is below. - -## What your README.md file should contain (bare minimum) - -At a minimum, your package's **README.md** file should include -(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. - -### βœ… Badges for current package version, continuous integration and test coverage - -Badges are a useful way to draw attention to the quality of your project and to -assure users that your package is well-designed, tested, and maintained. -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 should adding to your README file include: - -* Current version of the package on pypi / conda forge (the example badge below provides a github release value in our package guide isn't an installable tool.) - -![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic) - - -```markdown -Github release -![GitHub release (latest by date)](https://img.shields.io/github/v/release/your-github-org-name/package-repo-name?color=purple&display_name=tag&style=plastic) -``` - -* Continuous integration Status of tests (pass or fail) - -Circle CI badge: -[![CircleCI](https://circleci.com/gh/pyOpenSci/python-package-guide.svg?style=svg)](https://circleci.com/gh/pyOpenSci/python-package-guide) - -Example GitHub actions badge: - -![Docs Building](https://github.com/pyOpenSci/python-package-guide/actions/workflows/build-book.yml/badge.svg) - -``` -![Docs Building](https://github.com/pyOpenSci/python-package-guide/actions/workflows/build-book.yml/badge.svg) -``` - -* Citation badge (DOI). It is OK if you do not have a DOI prior to the review. [![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582) - -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 and accepted into the pyOpenSci scientific Python open source ecosystem! - - - -```{note} -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 - -At the top of your README file you should have a short, easy-to-understand, description that details the goals of your package and what purpose it serves. 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. - -Consider writing for a 12th grade reading level which is an ideal level for more scientific content that serves a broad user base. The goal of this description to maximize accessibility of your **README** file. - - -### βœ… BRIEF quickstart code demonstration of how to use the package - -Include a code quickstart that demonstrates how to use your package. -This quickstart should be simple. - -```{important} -### TOO MUCH OF A GOOD thing - -Try to avoid including several tutorials in the readme file itself. This too will overwhelm the user with information. - -A short quickstart vignette that shows a user how to use your package is plenty for the README file. All other tutorials and documentation should be presented as descriptive links. -``` - -### βœ… Descriptive links to package documentation, tutorials or vignettes. - -Include descriptive links in your README file to: - -* The package's documentation page. -* Tutorials or vignettes that demonstrate application of your package. - -### βœ… Discussion of how this package fits within the broader scientific python landscape. - -If applicable, describe how the package compares to other similar packages or complementary packages in the scientific Python ecosystem. This discussion can be brief. It's important for package maintainers to consider their package in the context of the broader ecosystem. You will be asked to do this when you submit your package for review for pyOpenSci. - -### βœ… Installation instructions - -Include instructions for installing your package. If you have published -the package on both `PyPI` and `Conda` be sure to include instructions for both. - -### βœ… Document any addition setup required to use you package - -Add any additional setup required that someone will need to do before using your package. Examples of additional setup steps including authentication tokens, or critical dependencies that don't get automatically installed when your package is installed. - -### βœ… Citation information - -Finally be sure to include instructions on how to cite your package. - -### βœ… Links to Contributing Guide, Code of Conduct -Last but not least provide direct links to your -**CONTRIBUTING** guide and to your project's **code of conduct**. - - -```{note} -### README Resources - -Below are some resources on creating great README.md files that you -might find helpful. - -* [The art of the README GitHub Repo](https://github.com/hackergrrl/art-of-readme) -* [Write a great readme - Bane Sullivan](https://github.com/banesullivan/README) -* [Readme resources from rOpenSci](https://devguide.ropensci.org/building.html#readme) -``` - - - - diff --git a/documentation/hosting-tools/intro.md b/documentation/hosting-tools/intro.md new file mode 100644 index 000000000..740a4b6d0 --- /dev/null +++ b/documentation/hosting-tools/intro.md @@ -0,0 +1,26 @@ +# 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 +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 +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. + +## Documentation build tools outline + +```{toctree} +:maxdepth: 2 + +Intro +Sphinx for Docs +myST vs Markdown vs rst +Publish Your Docs +Website Hosting and Optimization +``` diff --git a/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md b/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md new file mode 100644 index 000000000..d77a1dda0 --- /dev/null +++ b/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md @@ -0,0 +1,29 @@ +# 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 +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. + +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. +* 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. + + +```{tip} +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 new file mode 100644 index 000000000..df3220f87 --- /dev/null +++ b/documentation/hosting-tools/publish-documentation-online.md @@ -0,0 +1,44 @@ +# How to publish your Python package documentation online + +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. + +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 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 +* 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. + + +## 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. + + + +## 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. + +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, +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 new file mode 100644 index 000000000..72bb2a8df --- /dev/null +++ b/documentation/hosting-tools/sphinx-python-package-documentation-tools.md @@ -0,0 +1,67 @@ +# 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. + +```{tip} +Examples of documentation websites that we love: + +* [GeoPandas](https://geopandas.org/en/stable/) + * [View rst to create landing page](https://raw.githubusercontent.com/geopandas/geopandas/main/doc/source/index.rst) +* [verde](https://www.fatiando.org/verde/latest/) + * [View verde landing page code - rst file.](https://github.com/fatiando/verde/blob/main/doc/index.rst) +* [Here is our documentation if you want to see a myST example of a landing page.](https://github.com/pyOpenSci/python-package-guide/blob/main/index.md) +``` + +## 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 written using Python. + +### Sphinx sites can be customized using extensions and themes + +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. +* You can [automatically create documentation for your package's functions and classes (the package's API) from docstrings in your code using the autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) +* 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 + +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/) +* [sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/) +* [furo](https://pradyunsg.me/furo/quickstart/) + + +```{tip} +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 new file mode 100644 index 000000000..fc85f9630 --- /dev/null +++ b/documentation/hosting-tools/website-hosting-optimizing-your-docs.md @@ -0,0 +1,46 @@ +# 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. + +### 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. + +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. + +### [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 +is still important. Google is the most popular search engine. +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. + +This extension is lightweight. + +It [requires that you to add it to your Sphinx `conf.py` extension list and site your documentation base url.](https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html). + +### [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. diff --git a/documentation/index.md b/documentation/index.md index 97f45dd17..3a5eb8588 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -1,30 +1,146 @@ -# Intro: Document Your Python Package - -```{attention} -🚧 UNDER CONSTRUCTION - THIS CONTENT SHOULD BE FURTHER DEVELOPED BY THE END OF 2022! KEEP CHECKING BACK TO UPDATES AS THEY ARE IN PROGRESS🚧 +# 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. ``` -## Documentation is critical to the success of your Python open source package + + + + +## 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. While quality code is valuable as it gets the tasks that your -package seeks to achieve, completed, if users don't understand how to use the -tools in your package then they won't use your tool. +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. + +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 + +The documentation that you write for your +package should target two types of 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 +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 + in a research application. + * Information on the license that your code uses so they know how they can + or can't use the code in an operational setting. -## Documentation elements that we look for when reviewing a Python package +### 2. Potential tool contributors -In the pyOpenSci peer review process we look for several things when evaluating -package documentation including: +The other subset of users are more experienced and/or more engaged +with your package. As such they are +potential contributors. These users: -1. A clear and to the point **README.md** file -2. Documentation of the functionality of your code. This is often setup using Sphinx/ Read the docs or some other documentation platform -3. Sufficient API documentation of your packages API (this means that docstrings are formatted with explanations of each variable and better yet quick vignettes that demonstrate how to use the function or class). If you don't know what API documentation means this section is FOR YOU! -4. A **CONTRIBUTING.md** file that has clear instructions that others can follow to setup a development environment. This will support others contributing to your project. -5. A license file that helps people +* 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 +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. +``` + + +## 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 +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. + + + + +```{button-link} https://www.pyopensci.org/peer-review-guide/software-peer-review-guide/editor-in-chief-guide.html#editor-checklist-template +:color: primary +:class: sd-rounded-pill float-left +View pyOpenSci peer review check list +``` + + +```{figure} ../images/moving-pandas-python-package-github-main-repo.png +--- +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. +--- +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)* +``` - +## What's next in this Python package documentation section? +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. \ No newline at end of file diff --git a/documentation/repository-files/intro.md b/documentation/repository-files/intro.md new file mode 100644 index 000000000..40659e8f0 --- /dev/null +++ b/documentation/repository-files/intro.md @@ -0,0 +1,45 @@ +# 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, +at a minimum have the following files: + +```{toctree} +:maxdepth: 2 + +Intro +README file +Contributing File +Code of Conduct File +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. + +```{figure} /images/moving-pandas-python-package-github-community-standards.png +--- +name: directive-fig +width: 80% +alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including a description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo. +--- +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. + +```{figure} /images/moving-pandas-python-package-snyk-health.png +--- +name: directive-fig +width: 80% +alt: Screenshot of the Snyk page for movingpandas. It shows that the repository has a README file, contributing file, code of conduct. It also shows that it has 30 contributors and no funding. The package health score is 78/100. +--- +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 new file mode 100644 index 000000000..23c568f8c --- /dev/null +++ b/documentation/repository-files/license-files.md @@ -0,0 +1,36 @@ +# Your repository should have a LICENSE.md 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. + +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. + +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. +[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! +``` + +[The SciPy documentation has an excellent license discussion that is worth reading and considering for your project's development guide.](https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#licensing) + + + \ 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 new file mode 100644 index 000000000..be8774a76 --- /dev/null +++ b/documentation/repository-files/readme-file-best-practices.md @@ -0,0 +1,179 @@ +# 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. + +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 +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) + + +```{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. +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 +**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. + +Please go through this list before submitting your package to pyOpenSci + +``` +### pyOpenSci README checklist + +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) +- [ ] Easy-to-understand explanation (2-4 sentences) of what your tool does +- [ ] 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 +- [ ] Links to your package's documentation / website. +- [ ] A few descriptive links to any tutorials you've created for your package. +``` +```` + +## What your README.md file should contain + +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. + +### βœ”οΈ 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. +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. + +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 + +Example: [![PyPI version shields.io](https://img.shields.io/pypi/v/pandera.svg)](https://pypi.org/project/pandera/) + +* Status of tests (pass or fail) - Example: [![CI Build](https://github.com/pandera-dev/pandera/workflows/CI%20Tests/badge.svg?branch=main)](https://github.com/pandera-dev/pandera/actions?query=workflow%3A%22CI+Tests%22+branch%3Amain) + +* Documentation build - Example: ![Docs Building](https://github.com/pyOpenSci/python-package-guide/actions/workflows/build-book.yml/badge.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. +[![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/12) + +``` + + +```{caution} +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 + +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. + +```{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. + +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. + +### βœ”οΈ 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 +installation page in your online documentation here rather than over complicating +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. + +### βœ”οΈ Descriptive links to package documentation, short tutorials + +Include descriptive links to: + +* 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. + +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 + +Use your README.md file to direct users to more information on: + +* 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 +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. + +```{tip} +### README Resources + +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) +* [Art of README - Kira (@hackergrrl)](https://github.com/hackergrrl/art-of-readme) + +``` diff --git a/documentation/write-user-documentation/create-package-tutorials.md b/documentation/write-user-documentation/create-package-tutorials.md new file mode 100644 index 000000000..27e389c35 --- /dev/null +++ b/documentation/write-user-documentation/create-package-tutorials.md @@ -0,0 +1,156 @@ +# 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. + +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. + +## 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. + +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 +* [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. +* Render your tutorials with Python code and plot outputs + +### [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: + +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 + + +```{figure} /images/sphinx-gallery-overview.png +--- +name: directive-fig +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. +``` + +Below you can see what a tutorial looks like created with sphinx-gallery. + +```{figure} /images/sphinx-gallery-tutorial.png +--- +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. +--- +`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 +* easy-to-download notebook and .py outputs for each tutorials +* .py files are easy to work with in the GitHub pull request environment. +* Nice gridded gallery output +* Build execution time data per tutorial [Example](https://sphinx-gallery.github.io/stable/auto_examples/sg_execution_times.html) + +#### Sphinx gallery challenges + +The downsides of using Sphinx gallery include: + +* the **.py** files can be finicky to configure, particularly if you have matplotlib plot outputs. + +For example: To make allow for plots to render, you need to name each file with `plot_` +at the beginning. + +* Many users these days are used to working in Jupyter Notebooks. .py may be slightly less user friendly to work with + +These nuances can make it challenging for potential contributors to add +tutorials to your package. This can also present maintenance challenge. + +Add about the gallery setup - + +```bash +$ docs % make html + +Sphinx-Gallery successfully executed 2 out of 2 files +``` +File directory structure: + +```bash +tutorials/ + index.rst # landing page for your gallery + 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 + plot_sample-1.ipynb + plot_sample-1.py + ... + 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 + +``` + +### [nbsphinx - tutorials using Jupyter Notebooks](https://nbsphinx.readthedocs.io/en/latest/) + +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 + +* 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) + + +```{figure} /images/python-package-documentation-nb_sphinx-gallery-output.png +--- +name: directive-fig +width: 80% +alt: Image showing the gallery output provided by nbsphinx using the sphinx-gallery front end interface. +--- +`nbsphinx` can be combined with Sphinx gallery to create a gallery of tutorials. +However, rather render the gallery as a grid, it lists all of the gallery +elements in a single column. +``` + +```bash +tutorials/ + index.md # Landing page for your gallery + tutorial.ipynb # A tutorial in a jupyter notebook + another_tutorial.ipynb +# 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 + # the nbsphinx build - we will cover this in a separate tutorial series focused onPythonpackaging! + tutorials/ + index.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 new file mode 100644 index 000000000..a68e235d5 --- /dev/null +++ b/documentation/write-user-documentation/document-your-code-api-docstrings.md @@ -0,0 +1,207 @@ +# 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. + +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. + +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 +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. + +```{tip} +Example API Documentation for all functions, methods, attributes and classes in a package. +* [View example high level API documentation for the Verde package. This page lists every function and class in the package along with a brief explanation of what it does](https://www.fatiando.org/verde/latest/api/index.html) +* [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 + +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 +class, method, attribute and/or function in your package (*within reason*) that: + +* 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 +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) + + +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. +* 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. +``` + +### 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 +what the function does (2 to 3 sentences). The return of the function is also +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. + + Parameters + ---------- + ext_obj : list or geopandas.GeoDataFrame + If provided with a `geopandas.GeoDataFrame`, the extent + will be generated from that. Otherwise, extent values + should be in the order: minx, miny, maxx, maxy. + + Returns + ------- + extent_json: A GeoJSON style dictionary of corner coordinates + for the extent + A GeoJSON style dictionary of corner coordinates representing + the spatial extent of the provided spatial object. + """ +``` + + +(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 +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. + + Parameters + ---------- + ext_obj : list or geopandas.GeoDataFrame + If provided with a `geopandas.GeoDataFrame`, the extent + will be generated from that. Otherwise, extent values + should be in the order: minx, miny, maxx, maxy. + + Returns + ------- + extent_json : A GeoJSON style dictionary of corner coordinates + 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: + + >>> import geopandas as gpd + >>> import earthpy.spatial as es + >>> from earthpy.io import path_to_example + + We start by loading a Shapefile. + + >>> rmnp = gpd.read_file(path_to_example('rmnp.shp')) + + And then use `extent_to_json` to do the conversion from `shp` to + `geopandas.GeoDataFrame`. + + >>> es.extent_to_json(rmnp) + {'type': 'Polygon', 'coordinates': (((-105.4935937, 40.1580827), ...),)} + + """ + +``` + +```{figure} /images/sphinx-rendering-extent-to-json-earthpy.png +--- +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 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 +that the expected output is correct. Similar to running +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. +``` + +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. + + Parameters + ---------- + aNum : int + An integer value to be printed + + 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 +you provide it. + +>>> add_me(1+3) +4 + +``` diff --git a/documentation/write-user-documentation/get-started.md b/documentation/write-user-documentation/get-started.md new file mode 100644 index 000000000..f65f9f15f --- /dev/null +++ b/documentation/write-user-documentation/get-started.md @@ -0,0 +1,77 @@ +# Create User Facing Documentation for your Python Package + + + +## 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)`. + +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 +your Python package. [We discuss code documentation and docstrings in greater detail here.](document-your-code-api-docstrings) + +### 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. + +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. +* 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 +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. +* **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. + + +```{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. +--- +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 +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. +```` +```{include} ../README.md +``` +```` +````` diff --git a/documentation/write-user-documentation/intro.md b/documentation/write-user-documentation/intro.md new file mode 100644 index 000000000..72c9ca1ed --- /dev/null +++ b/documentation/write-user-documentation/intro.md @@ -0,0 +1,27 @@ +# Writing user-facing documentation for your Python package + +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 +create tutorials for your package. + +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, +classes, methods and attributes (API documentation) and +* sphinx gallery for tutorials. + +## User-facing documentation sections + +```{toctree} +:maxdepth: 2 + +Intro +Create Your Docs +Document Your Code (API) +Create Package Tutorials +``` + diff --git a/images/geopandas-documentation-landing-page.png b/images/geopandas-documentation-landing-page.png new file mode 100644 index 000000000..adc221fa4 Binary files /dev/null and b/images/geopandas-documentation-landing-page.png differ diff --git a/images/moving-pandas-python-package-github-community-standards.png b/images/moving-pandas-python-package-github-community-standards.png new file mode 100644 index 000000000..771ae6cfd Binary files /dev/null and b/images/moving-pandas-python-package-github-community-standards.png differ diff --git a/images/moving-pandas-python-package-github-main-repo.png b/images/moving-pandas-python-package-github-main-repo.png new file mode 100644 index 000000000..ddfad1c5f Binary files /dev/null and b/images/moving-pandas-python-package-github-main-repo.png differ diff --git a/images/moving-pandas-python-package-snyk-health.png b/images/moving-pandas-python-package-snyk-health.png new file mode 100644 index 000000000..9cb98210e Binary files /dev/null and b/images/moving-pandas-python-package-snyk-health.png differ diff --git a/images/pandera-python-package-readme-github.png b/images/pandera-python-package-readme-github.png new file mode 100644 index 000000000..0d33a91be Binary files /dev/null and b/images/pandera-python-package-readme-github.png differ diff --git a/images/python-package-documentation-nb_sphinx-gallery-output.png b/images/python-package-documentation-nb_sphinx-gallery-output.png new file mode 100644 index 000000000..749e5cd26 Binary files /dev/null and b/images/python-package-documentation-nb_sphinx-gallery-output.png differ diff --git a/images/sphinx-gallery-overview.png b/images/sphinx-gallery-overview.png new file mode 100644 index 000000000..f20193fcd Binary files /dev/null and b/images/sphinx-gallery-overview.png differ diff --git a/images/sphinx-gallery-tutorial.png b/images/sphinx-gallery-tutorial.png new file mode 100644 index 000000000..36fcd0317 Binary files /dev/null and b/images/sphinx-gallery-tutorial.png differ diff --git a/images/sphinx-rendering-extent-to-json-earthpy.png b/images/sphinx-rendering-extent-to-json-earthpy.png new file mode 100644 index 000000000..f79dfc994 Binary files /dev/null and b/images/sphinx-rendering-extent-to-json-earthpy.png differ diff --git a/index.md b/index.md index 5c531ed5a..d89f28d38 100644 --- a/index.md +++ b/index.md @@ -52,9 +52,10 @@ Learn about our open peer review process ✨ Documentation Criteria & Recommendations ✨ ^^^ -Learn about the good, better and best practices -associated with Python package documentation. Topics -covered include: README files, tutorials and full docs. +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} @@ -64,8 +65,9 @@ covered include: README files, tutorials and full docs. ✨ Package Structure & Code ✨ ^^^ - +Under Construction - Coming Spring 2023! +Learn more about standards for packaging structure and +builds in the scientific Python community. ::: :::{grid-item-card} @@ -111,36 +113,28 @@ to see here, [we invite you to open an issue on GitHub that details any changes :hidden: :caption: Documentation -Intro to Documentation -The README File -README Files -Package documentation -Contributing & license files +Documentation Overview +Write User Documentation +Core GitHub Repository Files +Documentation Tools & Hosting ``` + ```{toctree} :hidden: :caption: Package structure & code style -Intro -package-structure-code/code-structure-style -package-structure-code/release -package-structure-code/overview -package-structure-code/collaboration +Intro + ``` -```{toctree} -:hidden: -:caption: Code Style & Structure -code-style-structure/index -``` ```{toctree} :hidden: -:caption: Test your code -testing-infrastructure/test-code -testing-infrastructure/continuous-integration +:caption: CI and Testing + +Intro ``` diff --git a/noxfile.py b/noxfile.py index 0849be265..94cad603d 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,3 +1,6 @@ +import os +import pathlib +import shutil import nox nox.options.reuse_existing_virtualenvs = True @@ -25,4 +28,22 @@ def docs_live(session): for folder in AUTOBUILD_IGNORE: cmd.extend(["--ignore", f"*/{folder}/*"]) cmd.extend(build_command + session.posargs) - session.run(*cmd) \ No newline at end of file + session.run(*cmd) + +docs_dir = os.path.join("_build", "html") + +@nox.session(name="docs-clean") +def clean_dir(dir_path=docs_dir): + """ + Clean out the docs directory used in the + live build. + """ + dir_path = pathlib.Path(dir_path) + dir_contents = dir_path.glob('*') + + for content in dir_contents: + print(content) + if content.is_dir(): + shutil.rmtree(content) + else: + os.remove(content) \ No newline at end of file diff --git a/python-packaging/intro.md b/python-packaging/intro.md new file mode 100644 index 000000000..1c08d858f --- /dev/null +++ b/python-packaging/intro.md @@ -0,0 +1,11 @@ +# Python Packaging Tools... Coming soon... + + +In this section we will cover: + +* build tools to build your package +* publishing to PyPI and the Anaconda Cloud repositories +* Built front-end tools to support your development workflow +* Managing dependencies + +Stay tuned as this section is currently under development as of January 2023!! \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 61f066754..17741e6f0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ #ipython furo +sphinx_book_theme myst-nb sphinx sphinx-autobuild