From 5a63e76dc4e5114646bda2a6a46d3787a9361c0b Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 23 Nov 2022 11:06:49 -0700 Subject: [PATCH 1/5] Rebase --- code-style-structure/intro.md | 4 +- index.md | 32 +++-- .../code-structure-style.md | 134 ++++++++++++++++++ package-structure-code/collaboration.md | 55 +++++++ package-structure-code/intro.md | 43 ++++++ package-structure-code/release.md | 73 ++++++++++ package-structure-code/testing-ci.md | 83 +++++++++++ 7 files changed, 410 insertions(+), 14 deletions(-) create mode 100644 package-structure-code/code-structure-style.md create mode 100644 package-structure-code/collaboration.md create mode 100644 package-structure-code/intro.md create mode 100644 package-structure-code/release.md create mode 100644 package-structure-code/testing-ci.md diff --git a/code-style-structure/intro.md b/code-style-structure/intro.md index 7f540b30..a8bc5416 100644 --- a/code-style-structure/intro.md +++ b/code-style-structure/intro.md @@ -1,4 +1,6 @@ # Code style and structure -Under development \ No newline at end of file +Under development - possibly remove this as it's in the package structure +and might +make sense there. \ No newline at end of file diff --git a/index.md b/index.md index 2c73e7b1..0712b723 100644 --- a/index.md +++ b/index.md @@ -2,6 +2,7 @@ + ## Welcome, Python open source enthusiast! Here you will find guidelines for what we look for in your scientific @@ -21,19 +22,12 @@ Python package when reviewing. You will also find best practice recommendations :class: sd-fs-3 - +Learn about our open peer review process +``` ```{only} html ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic) @@ -123,11 +117,23 @@ Package docs & tutorials Contributing & license files ``` + +```{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 +``` + ```{toctree} :hidden: -:caption: Package structure -I don't work -I work +:caption: Code Style & Structure + +code-style-structure/index ``` ```{toctree} diff --git a/package-structure-code/code-structure-style.md b/package-structure-code/code-structure-style.md new file mode 100644 index 00000000..66da05b0 --- /dev/null +++ b/package-structure-code/code-structure-style.md @@ -0,0 +1,134 @@ +# Code Style and Structure + +pyOpenSci suggests that you follow the [python PEP8 style guide](https://peps.python.org/pep-0008/) for decisions +related to styling your open source Python packages code. + +We also suggest that you consider: +1. adhering to a commonly used docstring format. If you use xx or xx then it will further support easy API documentation using tools such as Sphinx autodoc. +2. Adding a linter to your development build that will catch style issues and tell you how to reformat your code as needed. (see below for more ) +3. Add a code styler such as black or blue to keep the entire package consistent. + +## Docstring styles + +```{note} +what is a docstring... +https://peps.python.org/pep-0257/#what-is-a-docstring +``` + +* https://numpydoc.readthedocs.io/en/latest/ +* Ask on slack this week what resources people like for this + +## Code linters + +Code linters are tools that look at your code and identify problems such as: + +* unused variables +* invalide styles +* missing docstrings +* incorrect spacing + +and more + +Linters can be run as a command-line tool and/or can also be setup as a part of +your favorite programming tool (e.g. VScode, pycharm, etc). + +Some maintainers stup a pre-commit hook in their reporisoty. A hook will check +your code prior to your committing it. IT will itendify issues and if the +hook includes a styler, will fix any issues with code style before you commit. + +This type of setup can be helpful to ensure code consistency associated with new +contributions... + + +Regardless of how you set this up, We suggest setting up a linter and a code styler +as they will give you automatic feedback about your code's structure as you (or a contributor) write it. + +## Some popular linters + +* A very popular code linter for Python is [flake8](https://flake8.pycqa.org/en/latest/). +`Flake8` checks if the code is according to [PEP 8](https://www.python.org/dev/peps/pep-0008/), +the Python Enhancement Proposal about `Style Guide for Python Code`. + + +See also: + +- [mypy](http://mypy-lang.org/) +- [numpydoc](https://numpydoc.readthedocs.io/en/latest/) +- [pydocstyle](https://github.com/PyCQA/pydocstyle) + + +## Code stylers + +Code stylers are tools that fix styling issues in a file, formatting it automatically. +Code *styling* is different from code *linting* because it doesn't change the functionality +of your code at all, it *only* changes how it looks. +Using an automatic formatting tool helps to keep the source code within specification +and also helps review workflow. While stylers might cause your code to look differently +than you would have chosen, many projects have adopted them in order to have a single +code style that is consistent across projects. + +Currently, [black](https://github.com/psf/black) is the most popular code styler for Python. +It will format the code according the `PEP 8` and should work fine with `flake8` (maybe it needs +some extra configuration as, for example, `line-length`). + +See also: + +- [isort](https://github.com/timothycrosley/isort) + + +## Git pre-commit hook + +Git pre-commit hook is a useful tool that checks your code automatically when you run a `git commit` and, +if it fails, the `git commit` is canceled. This is often used to make sure +that the changes to your code match a particular style, or that there are no +code linting errors. + +For example, if you want that `git commit` checks if your code matches the PEP8 specification, +you can configure a git flake8 pre-commit hook: + + +```yaml +# file: .pre-commit-config.yaml +repos: + - repo: https://gitlab.com/pycqa/flake8 + rev: '3.7.9' + hooks: + - id: flake8 + +``` + +```{note} +See [the flake8 hooks explanation](https://flake8.pycqa.org/en/latest/user/using-hooks.html) for more details. +``` + +This file specifies a hook that will be triggered automatically before each `git commit`, +in this case, it specifies a flake8 using version `3.7.9`. + +Before you can see any change, first you should install `pre-commit` library. +One way to do it is using `pip` or `conda`: + +```sh +pip install pre-commit + +# or + +conda install -c conda-forge pre-commit +``` + +Now, you can install your pre-commit hook using `pre-commit install`, and it will create the hook based on +the file `.pre-commit-config.yaml`. + +Before each `git commit` command, in this case, git will run `flake8` and, if it fails, the `commit` will be canceled. + + +## What git pre-commit hook should I use? + +The git pre-commit hook you should use, depends on the project needs or the team needs. +Some pre-commit hooks you can find useful would be: + +- [flake8](https://flake8.pycqa.org/en/latest/user/using-hooks.html) +- [mypy](https://github.com/pre-commit/mirrors-mypy) +- [black](https://black.readthedocs.io/en/stable/integrations/source_version_control.html) +- [isort](https://github.com/pre-commit/mirrors-isort) + +If you want more information about `pre-commit`, check out its [documentation](https://pre-commit.com/). diff --git a/package-structure-code/collaboration.md b/package-structure-code/collaboration.md new file mode 100644 index 00000000..c2cee89f --- /dev/null +++ b/package-structure-code/collaboration.md @@ -0,0 +1,55 @@ +# Collaboration Guide + +🚧 UNDER CONSTRUCTION - THIS CONTENT SHOULD BE FURTHER DEVELOPED BY THE END OF 2022! KEEP CHECKING BACK TO UPDATES AS THEY ARE IN PROGRESS🚧 + + +Note: pyOpenSci is still building out this section of our guidebook. Many of the examples come from rOpenSci. If you have suggestions for changes, check out the [GitHub repo](https://github.com/pyOpenSci/contributing-guide). + +## Make your repo contribution and collaboration friendly + +### Code of conduct + +We require that you use a code of conduct such as the [Contributor Covenant](https://contributor-covenant.org/) in developing your package. You should document your code of conduct in a `CODE_OF_CONDUCT` file in the package root directory, and link to this file from the `README` file. + +### Contributing guide + +October 2022 NOTE: we are in the process of updating all of this and will likely deprecate +this cookie cutter. Proceed at your own risk :) + +We have a [template for contributing guidelines](https://github.com/pyOpenSci/cookiecutter-pyopensci/blob/master/%7B%7Bcookiecutter.project_slug%7D%7D/CONTRIBUTING.rst) in our cookiecutter repository. Even if you're not using cookiecutter to build your project (see our [packaging guide](../authoring/overview#project-template) for info), you can download our CONTRIBUTING.rst as a starting point. + +You can tweak it a bit depending on your workflow and package. For example, make sure contributors have instructions in your CONTRIBUTING file for running local tests if not trivial. CONTRIBUTING can also contain some details about how you acknowledge contributions (see [this section](#attributions)) and the roadmap of your package (cf [this example for R](https://github.com/ecohealthalliance/fasterize/blob/master/CONTRIBUTING.md)). + +### Issue labelling + +You can use labels such as "help wanted", "good first issue", or "beginner" to help potential collaborators, including newbies, find your repo. For more info, see this [GitHub article](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/encouraging-helpful-contributions-to-your-project-with-labels). + +## Working with collaborators + +### Onboarding collaborators + +There's no general pyOpenSci rule as to how you should onboard collaborators. You should increase their rights to the repo as you gain trust, and you should definitely acknowledge contributions (see [this section](#attributions)). + +You can ask a new collaborator to make PRs (see following section for assessing a PR locally, i.e. beyond CI checks) to dev/main and assess them before merging, and after a while let them push to main, although you might want to keep a system of PR reviews... even for yourself once you have team mates! + +A possible model for onboarding collaborators is provided by Jim Hester in [his `lintr` repo](https://github.com/jimhester/lintr/issues/318). + +If your problem is _recruiting_ collaborators, you can post an open call like Jim Hester's [on Twitter](https://twitter.com/jimhester_/status/997109466674819074), ([GitHub](https://github.com/jimhester/lintr/issues/318)). As an pyOpenSci package author, you can also ask for help from pyOpenSci. + +### Working with collaborators (including yourself) + +You could implement the "[gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)" philosophy as explained by Amanda Dobbyn in [this rOpenSci blog post](https://ropensci.org/blog/2018/04/20/monkeydo/). + +One particular aspect of working with collaborators is reviewing pull requests. Even if not adopting gitflow it might make sense for repo collaborators to make PRs and have them reviewed, and in general PRs by external developers will need to be assessed. Sometimes you'll be fine just reading the changes and trusting [Continuous integration](../authoring/overview#continuous-integration). Sometimes you'll need to dive deeper, e.g. by downloading a copy of the branch that the PR was created from. + +(attributions)= +### Be generous with attributions + +If someone contributes to your repository consider adding them in CONTRIBUTORS, as contributor for small contributions, author for bigger contributions. Also consider adding their name near the feature/bug fix line in HISTORY We recommend your being generous with such acknowledgements. + +If your package was reviewed by pyOpenSci and you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in CONTRIBUTORS as a reviewer. Only include reviewers after asking for their consent. + +```{note} +Please do not list pyOpenSci editors and reviewers as contributors to your project. +Your participation in and contribution to pyOpenSci is thanks enough! +``` diff --git a/package-structure-code/intro.md b/package-structure-code/intro.md new file mode 100644 index 00000000..4fed62bc --- /dev/null +++ b/package-structure-code/intro.md @@ -0,0 +1,43 @@ +# Python package structure information + + +Resources + +https://merely-useful.tech/py-rse/ + +If you plan to submit a package for review to pyOpenSci and are looking for +some guidance on package structure, code formats and style, then this section is for you. + + + + +If you are looking for a more comprehensive guide to Python packaging we suggest +you review the following excellent resources: + +## TODO: ***** add resource list here ***** + +```{note} +If you are considering submitting a package to pyOpenSci, or if you are just +getting started with building a package, you may want to have a look at the +bare-minimum [editor checks.](open-source-software-submissions/editor-in-chief-guide.html#editor-checklist-copy-template-below-to-use-in-the-issue) that pyOpenSci +performs before a review even begins. + +In general these are basic items that should be in any open software repository. +``` + +## Packaging Guide + + +PyPI also has a [short tutorial](https://packaging.python.org/tutorials/packaging-projects/) +on how to package a Python project for easy installation. + + + + + diff --git a/package-structure-code/release.md b/package-structure-code/release.md new file mode 100644 index 00000000..b13ec9b0 --- /dev/null +++ b/package-structure-code/release.md @@ -0,0 +1,73 @@ +# Releasing a package + +🚧 UNDER CONSTRUCTION - THIS CONTENT SHOULD BE FURTHER DEVELOPED BY THE END OF 2022! KEEP CHECKING BACK TO UPDATES AS THEY ARE IN PROGRESS🚧 + + +This section covers releasing your package to PyPI as well as releasing future versions. Your package should have different versions over time: snapshots of a state of the package that you can release to PyPI for instance. These versions should be properly _numbered_, _released_ and _described in a NEWS file_. More details below. + + +## Original Release + +After the review process has finished, you're ready to release your package to PyPI so others can find and use your awesome package! Releasing to PyPI is easy. Once your package is ready, register it on PyPI by running: + +``` +python setup.py register +``` + +## Releasing Updated Versions + +When you update your package, you release a new version to PyPI. Fortunately, this is easy! First, we'll talk about the metadata you'll need to update for each version. Then we'll cover how to release your updated version to PyPI [manually via the command line](manual-release) or [automatically via Travis CI](travis-release). + +### Version Naming + +* We recommend that pyOpenSci packages use [semantic versioning](https://www.python.org/dev/peps/pep-0440/#semantic-versioning). In addition to the [PEP section on it](https://www.python.org/dev/peps/pep-0440/#semantic-versioning), [the semver website has more detail](https://semver.org/). + +* Versioning can be done using [bumpversion](https://github.com/peritus/bumpversion), e.g. for a minor update: + +``` +bumpversion minor +``` + +"minor" can be replaced with "major" or "patch" depending on the level of update. + +(history)= +### History/News/Changelog file + +A HISTORY (or NEWS or CHANGELOG) file describing changes associated with each version makes it easier for users to see what's changing in the package and how it might impact their workflow. You must add one for your package, and make it easy to read. + +* It is mandatory to use a `HISTORY` file in the root of your package. It can also be called NEWS or CHANGELOG We recommend using `[NAME].md` or `[NAME].rst` to make the file more browsing-friendly on GitHub (GitHub renders certain file types, including Markdown and reStructured text). + +* Update the history file before every PyPI release, with a section with the package name, version and date of release. + +``` +foobar 0.2.0 (2016-04-01) +========================= +``` + +* Under that header, put in sections as needed, including: `NEW FEATURES`, `MINOR IMPROVEMENTS`, `BUG FIXES`, `DEPRECATED AND DEFUNCT`, `DOCUMENTATION FIXES` and any special heading grouping a large number of changes. Under each header, list items as needed. For each item give a description of the new feature, improvement, bug fix, or deprecated function/feature. Link to any related GitHub issue like `(#12)`. The `(#12)` will resolve on GitHub in Releases to a link to that issue in the repo. + +* After you have added a `git tag` and pushed up to GitHub, add the news items for that tagged version to the Release notes of a release in your GitHub repo with a title like `pkgname v0.1.0`. See [GitHub docs about creating a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). + +(manual-release)= +### Releasing Versions: Manual + +To manually upload a new package version to PyPI, follow these steps: + +1. Update your HISTORY file as described [above](#history) +2. Open `setup.py` and change the version, e.g., version='1.0.3' +3. If you added new, non-Python files to the project that need to be distributed as well, e.g., configuration files, add them to `MANIFEST.in`. This does not need to be done for Python code files ending in .py. +4. Open a terminal and go into the parent of the project's root dir +5. `python setup.py sdist` +6. Check the resulting files, especially the egg file: are all the files contained? +7. If everything is ok, upload the new version to PyPI: `python setup.py sdist upload` + +That's it! + +(travis-release)= +### Releasing via Travis CI +Instead of manually uploading new package versions, Travis can be configured to automatically upload new versions. If you use this, each time you tag a new release and push it to GitHub, Travis will release it to PyPI (assuming it passes testing). + +* The pyOpenSci cookiecutter comes with this option mostly set up. For details on how to finish the set up, see [this guide](https://cookiecutter-pyopensci.readthedocs.io/en/latest/travis_pypi_setup.html). + +* Also, be sure to check out this [PyPI release checklist](https://cookiecutter-pyopensci.readthedocs.io/en/latest/pypi_release_checklist.html). + diff --git a/package-structure-code/testing-ci.md b/package-structure-code/testing-ci.md new file mode 100644 index 00000000..b323b82c --- /dev/null +++ b/package-structure-code/testing-ci.md @@ -0,0 +1,83 @@ +# Testing and CI?? + + + + + + +### Testing +- All packages should have a test suite that covers major functionality of the package. The tests should also cover the behavior of the package in case of errors. +- It is good practice to write unit tests for all functions, and all package code in general, ensuring key functionality is covered. Test coverage below 75% will likely require additional tests or explanation before being sent for review. +- We recommend using pytest for writing tests, but you can use other tools. Strive to write tests as you write each new function. This serves the obvious need to have proper testing for the package, but allows you to think about various ways in which a function can fail, and to defensively code against those. +- Consider using tox to test your package with multiple versions of Python 2 and 3. +- If you set up CI with code coverage, use your package's code coverage report to identify untested lines, and to add further tests. + +**Good/Better/Best:** +- **Good:** A test suite that covers major functionality of the package. +- **Better:** The above, with high code coverage. +- **Best:** All of the above, plus using tox to test multiple versions of Python. + +### Continuous Integration +All pyOpenSci packages must use some form of continuous integration. + +- For Linux and Mac OSX, we suggest GitHub Actions, Circle CI or Travis CI. +- For Windows, we suggest GitHub Actions or AppVeyor CI. +- In many cases, you will want CI for all platforms. Different continuous integration services will support builds on different operating systems. Packages should have CI for all platforms when they contain: + - Compiled code + - Java dependencies + - Dependencies on other languages + - Packages with system calls + - Text munging such as getting people’s names (in order to find encoding issues). + - Anything with file system / path calls + - In case of any doubt regarding the applicability of these criteria to your package, it’s better to add CI for all platforms, and most often not too much hassle. + +**Good/Better/Best:** +- **Good:** Some sort of CI service with status badge in your README. +- **Better:** The above plus integrated code coverage and linting. +- **Best:** Continuous integration for all platforms: Linux, Mac OSX, and Windows. + + + + + +This section provides guidelines and tips for creating a Python package to submit for peer-review. + +pyOpenSci packages must: +- Have a clear README _including_ installation instructions. +- Contain full documentation for any user-facing functions. +- Have a test suite that covers the major functionality of the package. +- Use continuous integration. +- Use an OSI approved software license. + + + + + +### 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. + +**Good/Better/Best:** +- **Good:** Include a open source software license with your package. +- **Better/Best:** Choose a license based on your needs and future use of package, plus explain your choice in your submission for review. + +## Other recommendations +### Python version support +You should always be explicit about which versions of Python your package supports. +Keeping compatibility with old Python versions can be difficult as functionality changes. +A good rule of thumb is that the package should support, at least, +the latest three Python versions (e.g., 3.8, 3.7, 3.6). + +### Code Style +pyOpenSci encourages authors to consult [PEP 8](https://www.python.org/dev/peps/pep-0008/) for information on how to style your code. + +### Linting +An automatic linter (e.g. flake8) can help ensure your code is clean and free of syntax errors. These can be integrated with your CI. + +### Badges + +Badges are a useful way to draw attention to the quality of your project and to +assure users that it is well-designed, tested, and maintained. +It is common to provide a collection of badges in a table for others +to quickly browse. + +[See this example of a badge table](https://github.com/ropensci/drake). Such a table should be more wide than high. (Note that the badge for pyOpenSci peer-review will be provided upon acceptance.) From 85800bc13dfbfc50300c77196bcdf2f84a2be644 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 23 Nov 2022 11:09:34 -0700 Subject: [PATCH 2/5] Cleanup rebase --- code-style-structure/intro.md | 2 +- documentation/readme-files.md | 136 ++++++++++++++++++++++++++++++++ index.md | 5 +- package-structure-code/intro.md | 7 +- 4 files changed, 145 insertions(+), 5 deletions(-) create mode 100644 documentation/readme-files.md diff --git a/code-style-structure/intro.md b/code-style-structure/intro.md index a8bc5416..474b1cc5 100644 --- a/code-style-structure/intro.md +++ b/code-style-structure/intro.md @@ -1,4 +1,4 @@ -# Code style and structure +# DELETE ME Code style and structure Under development - possibly remove this as it's in the package structure diff --git a/documentation/readme-files.md b/documentation/readme-files.md new file mode 100644 index 00000000..cc29e77b --- /dev/null +++ b/documentation/readme-files.md @@ -0,0 +1,136 @@ +# README File Guidelines and Resources + +The **README.md** file is often the first thing that someone sees before they +instal your package. + +This file is the landing page of: + +* Your file on package manager landing pages like PyPI and Anaconda +* Your package's GitHub repository + +It is also used to measure: +* community health by github +* and included in package health landing pages such as snyk + +Thus, it is important that you spend some time up front creating a high quality +**README.md** file for your Python package. + +## TODO ADD screenshots of landing pages in github and pypi + +Your README.md file should be located in the root of your GitHub repository. + +## TODO provide some screenshots of our repo with a readme file + +## 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 readthedocs bade to your readme 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 / conda + +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 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. +``` + +### ✔️ 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 + +Add any additional setup required such as authentication tokens, to +get started using your package. If setup is complex, consider linking to a +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 quick start vignette that provides a code sample demonstrating use of our package. + +### ✔️ Descriptive links to package documentation, tutorials or vignettes. + +Include descriptive links to to: + +* The package's documentation page. +* Tutorials or vignettes that demonstrate application of your package. + +```{tip} +### 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 quick-start 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. +``` + +### ✔️ Community links Links to Contributing Guide, Code of Conduct +In your readme file direct users to more information on: +* contributing to your package +* development setup for more advanced technical contributors +* your code of conduct. + +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. + + +```{tip} +### README Resources + +Below are some resources on creating great README.md files that you +might find helpful. + +* [Write a great readme - Bane Sullivan](https://github.com/banesullivan/README) +* [The art of the README GitHub Repo](https://github.com/hackergrrl/art-of-readme) + +``` diff --git a/index.md b/index.md index 0712b723..f30f85b4 100644 --- a/index.md +++ b/index.md @@ -107,22 +107,23 @@ Good meets the requirements. Going beyond the minimum can make package maintenan 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). + ```{toctree} :hidden: :caption: Documentation Intro to Documentation The README File +README Files Package docs & tutorials Contributing & license files ``` - ```{toctree} :hidden: :caption: Package structure & code style -intro +Intro package-structure-code/code-structure-style package-structure-code/release package-structure-code/overview diff --git a/package-structure-code/intro.md b/package-structure-code/intro.md index 4fed62bc..565cd193 100644 --- a/package-structure-code/intro.md +++ b/package-structure-code/intro.md @@ -1,9 +1,12 @@ # Python package structure information +```{tip} +### Resources that we love +can i make the language in the yellow bar instead ofa heading -Resources +* [Python packaging for research software engineers](https://merely-useful.tech/py-rse/) -https://merely-useful.tech/py-rse/ +``` If you plan to submit a package for review to pyOpenSci and are looking for some guidance on package structure, code formats and style, then this section is for you. From 1f8f5a568958c000d753bb6c0284578626c6b0b0 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 23 Nov 2022 11:10:10 -0700 Subject: [PATCH 3/5] inde --- index.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/index.md b/index.md index f30f85b4..ffce6859 100644 --- a/index.md +++ b/index.md @@ -144,14 +144,7 @@ testing-infrastructure/test-code testing-infrastructure/continuous-integration ``` - + From 88ef968299f729b8fb0bafd659a7580f5ee8965f Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 23 Nov 2022 12:49:19 -0700 Subject: [PATCH 4/5] Move to furo and more edits to documentation section --- _static/pyos.css | 93 +------- conf.py | 2 +- documentation/create-readme-files.md | 211 ------------------ documentation/index.md | 19 +- ...als.md => package-documentation-sphinx.md} | 119 ++++++---- documentation/readme-files.md | 22 ++ index.md | 4 +- requirements.txt | 4 +- 8 files changed, 117 insertions(+), 357 deletions(-) delete mode 100644 documentation/create-readme-files.md rename documentation/{package-documentation-tutorials.md => package-documentation-sphinx.md} (72%) diff --git a/_static/pyos.css b/_static/pyos.css index f894a1d8..4e9f77b5 100644 --- a/_static/pyos.css +++ b/_static/pyos.css @@ -1,93 +1,20 @@ html, body { - font-size: 1.1rem; + font-size: 1.02rem; } -body p { - /* font-family: $header-font; */ - font-size: 1em; - font-family: 'Verdana', sans-serif!important; - color: #555!important; - line-height: 1.5em; -} - -h1, h2, h3 { - font-family: 'Trebuchet MS', sans-serif; - color: #333!important; +.admonition { + margin-top: 40px; + margin-bottom: 40px; } h1 { - padding-bottom: 1em!important; -} - -h3 { - padding-top: 1.4em; - margin-bottom: 14px; -} - -/* hide the right sidebar */ -.col-md-3 .bd-toc .show .noprint { - display: none!important; -} - -#main-content { - max-width: 80%; -} - -.bd-toc { - color: #1abc9c; -} - -@media (min-width: 720px){ -.col-md-3 { - flex: 0 0 25%; - /* max-width: 25%; */ - display: none!important; - } -} - - -/* HEADER BLOCK 2 */ -div.header__block { -color: #222; + margin-top: 40px; + margin-bottom: 40px; } - -.announcement div { -background-color: #ccc; -} - -.header-item.announcement, .header-item.announcement .noprint { - background-color:#ccc; -} - -div .announcement .header-item .noprint, header-item.announcement { - background-color: #ccc!important; -} - -/* notes */ - -div.admonition.note .admonition-title, div.admonition.note .admonition-title::before { - background-color: #C1CFD4; - color: #222; - +h2 { + margin-top: 60px; } -div.admonition.note { - border-color: #C1CFD4; - background-color: #E3F4FA; -} - - -div.admonition.important .admonition-title, div.admonition.important .admonition-title::before { -background-color: #107762; -color: #ffffff!important; -} - -div.admonition.important .admonition-title { -background-color: #107762; -border-color: #1abc9c; -} +h3 { + margin-top: 40px} -div.admonition.important { - border-color: #0e6654; - background-color: #ecfcf9; -} diff --git a/conf.py b/conf.py index 1839adea..cd043e7d 100644 --- a/conf.py +++ b/conf.py @@ -77,7 +77,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_book_theme' +html_theme = 'furo' html_static_path = ["_static"] html_css_files = ["pyos.css"] html_title = "pyOpenSci Package Guide" diff --git a/documentation/create-readme-files.md b/documentation/create-readme-files.md deleted file mode 100644 index dce586e2..00000000 --- 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/index.md b/documentation/index.md index 97f45dd1..7c464b41 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -6,20 +6,23 @@ ## Documentation is critical to the success of your Python open source package 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 it gets the tasks +that your package seeks to achieve, done. However, if users don't understand +how to use the tools in your package, then they won't use your tool. + +Further, if you wish to build a base of contributors to your package, having +explicit information about how to contribute is critical. ## Documentation elements that we look for when reviewing a Python package In the pyOpenSci peer review process we look for several things when evaluating package documentation including: -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 +1. [A clear and to the point **README.md** file](readme-files) +2. **Clear package documentation** that helps users understand how to install, use and cite your package. Package documentation is often setup using [Sphinx](https://www.sphinx-doc.org/en/master/) which is a Python-focused documentation engine. You can host your documentation using github pages or an online tool like [readthedocs](https://www.readthedocs.org). +3. **Package API documentation.** Package API documentation refers to documentation for each class, function, method and attribute that is user facing in your package. This mean means that your package methods and classes have docstrings that 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 outlines how others can contribute to your package. This file should also link to your development guide and code of conduct.A well-crafted contributing guide will make it much easier for the community to contribute to your project. +5. A license file. diff --git a/documentation/package-documentation-tutorials.md b/documentation/package-documentation-sphinx.md similarity index 72% rename from documentation/package-documentation-tutorials.md rename to documentation/package-documentation-sphinx.md index 30d16870..0908fb74 100644 --- a/documentation/package-documentation-tutorials.md +++ b/documentation/package-documentation-sphinx.md @@ -1,51 +1,59 @@ # Python Package Documentation -```{note} -Examples of documentation that we love: +In addition to a well designed [README FILE](create-readme-files) +there are several core components of Python package documentation +including: -* [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) -``` +* **User-facing documentation:** This refers to easy-to-read documentation that a user will review. This documentation should help users install and use your package. +* **API documentation:** this is documentation contained within the docstrings of all user-facing functions, methods and classes in your package. +## User-facing documentation for your Python package: -## Package documentation +User-facing documentation is often an easy to navigate website written with +user friendly, less technical language. User facing documentation should be: -Your package should have user-facing and API focused documentation. We suggest -that you setup a website to host your documentation. -Many prefer to use Sphinx to create -their Python package documentation. Sphinx is a useful tool as it offers extensions -that support things like: +* easy to read (consider writing for a 12th grade audience) +* contain tutorials or vignettes that support getting started using your package -* [automatically documenting your API using docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) -* running and testing code examples in your docstrings +### What tools to use in building your documentation: sphinx -## Documentation landing page best practices +Most python packages maintainers use [sphinx](https://www.sphinx-doc.org/) to build their documentation. +Sphinx has documentation themes that give your docuemntation a clean online look that are easy to apply to your +package's documentation. -To make it easy for users to find what they need quickly, all packages should -have 4 elements on the home page of their documentation: +While you are free to use whatever theme works for you, +the most common modern templates that we see in the scientific +community currently and recommend are: -* **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. -* **About:** Describe your project, state project goals and what it does. -* **Community:** Instructions for ho to help and/or get involved. This section might include a development guide. -* **Documentation:** The actual project documentation. You may have two sections of documentation - the user facing documentation and your API reference. +* [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/) +* [sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/) +* [furo](https://pradyunsg.me/furo/quickstart/) -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. -Some packages +Both of the above themes support [myst](https://myst-parser.readthedocs.io/) which allows you to build your package +documentation in `markdown` rather than `.rst`. -### Sphinx themes -Sphinx also offers numerous themes that you can use to customize your documentation. -A few Sphinx themes that are commonly used in the Scientific Python community that you might -consider include: +Sphinx also offers extensions that support things like: -* [pydata sphinx theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) -* [sphinx book theme](https://sphinx-book-theme.readthedocs.io/en/stable/) +* [automatically documenting your API using docstrings in your code](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) +* [running and testing code examples in your docstrings (doctest)](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) -This contributing guide is created using a modified version of the Spinx Book -theme. +```{tip} +This book is created using sphinx and the `furo` theme. + +``` + +### How to host your documentation + +We suggest that you setup a website to host your documentation. There are two ways +to do this: + +1. You can host your documentation yourself using gh-pages or another online hosting service. +2. You can host your documentation using ReadTheDocs. + +If you don't want to maintain a documentation website for your Python package, we +suggest using the [READTHEDOCS platform](https://www.readthedocs.org) which +allows you to easily host your documentation and track versions of your docs +as you release updates. ### myST vs rst syntax to create your docs There are two commonly used syntaxes for creating docs: @@ -56,32 +64,35 @@ There are two commonly used syntaxes for creating docs: There is no wrong or right when choosing a syntax to write your documentation. Choose whichever syntax works best for you and your community! -```{note} +```{tip} If you are on the fence about myST vs rst, you might find that *myST* is easier for more people to contribute to. ``` -### Publish your docs on another platform directly from GitHub: ReadTheDocs.org -If you don't want to maintain a documentation website for your Python package, we -suggest using the [READTHEDOCS platform](https://www.readthedocs.org) which -allows you to easily host your documentation and track versions of your docs -as you release updates. +## Documentation landing page best practices -Beyond a well designed [README FILE](create-readme-files) there are several -core components of Python package documentation including: +To make it easy for users to find what they need quickly, all packages should +have 4 elements on the home page of their documentation: -1. User facing documentation -2. API documentation +* **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. +* **About:** Describe your project, state project goals and what it does. +* **Community:** Instructions for ho to help and/or get involved. This section might include a development guide. +* **Documentation:** The actual project documentation. You may have two sections of documentation - the user facing documentation and your API reference. -## User-facing documentation for your Python package: +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. -User-facing documentation is often an easy to navigate website written with -user friendly, less technical language. User facing documentation should be: +`````{tip} +You can include files in sphinx using the include directive. +Below is an example of doing this using `myst` syntax. +```` +```{include} ../README.md +``` +```` +````` -* easy to read (consider writing for a 12th grade audience) -* contain tutorials or vignettes that support getting started using your package ## Python package API documentation @@ -156,3 +167,13 @@ def extent_to_json(ext_obj): ``` + +```{note} +Examples of documentation 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) +``` diff --git a/documentation/readme-files.md b/documentation/readme-files.md index cc29e77b..2a56be78 100644 --- a/documentation/readme-files.md +++ b/documentation/readme-files.md @@ -21,6 +21,28 @@ Your README.md file should be located in the root of your GitHub repository. ## TODO provide some screenshots of our repo with a readme file + +````{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. +``` +```` + ## What your README.md file should contain Your **README.md** file should contain the following things (listed from top to bottom): diff --git a/index.md b/index.md index ffce6859..1d8985c6 100644 --- a/index.md +++ b/index.md @@ -63,7 +63,7 @@ covered include: README files, tutorials and full docs. :link-type: doc :class-header: bg-light -✨ Coming soon... ✨ +✨ Package Structure & Code ✨ ^^^ @@ -115,7 +115,7 @@ to see here, [we invite you to open an issue on GitHub that details any changes Intro to Documentation The README File README Files -Package docs & tutorials +Package documentation Contributing & license files ``` diff --git a/requirements.txt b/requirements.txt index 662977fd..e6feb40b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,4 @@ -#ipython -sphinx-book-theme -myst-parser[linkify] +furo myst-nb sphinx sphinx-autobuild From cac936668837025d44ea7b938d51ad2f8d362b17 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 23 Nov 2022 13:07:19 -0700 Subject: [PATCH 5/5] add dev guide --- documentation/contributing.md | 46 +++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/documentation/contributing.md b/documentation/contributing.md index 75c6a0fa..dbe08772 100644 --- a/documentation/contributing.md +++ b/documentation/contributing.md @@ -1,19 +1,14 @@ -# CONTRIBUTING file and License +# Contributing and License Files in your Python Package -## 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.md** file). -Your python package should include a file called CONTRIBUTING.md located in the -root of your repository (with your readme file). +## What should be in the contributing guide -### Local development environment information +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 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: @@ -21,7 +16,32 @@ submitting issues or pull requests: * A link to your code of conduct * A link to or include how your code of conduct is enforced. -```{note} +It should also include informative descriptive links for a +development guide (see below) that has instructions for: + +* Setting up a development environment locally to work on your package +* How the test suite is setup and run +* How you can build docs locally + +## Development guide for your package + + + +### Why a development guide is important + +While 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), 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 code based pr's + +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. + + + +```{tip} [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/) ```