From 78ff4ddedabfa48bcefd80501d6ad0434f1a01e4 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 27 Feb 2024 12:58:13 -0800 Subject: [PATCH 01/10] make index page match toctree structure --- _static/pyos.css | 2 +- index.md | 27 ++++++++++++++++++++------- 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/_static/pyos.css b/_static/pyos.css index 9426d7e9..d94fb75a 100644 --- a/_static/pyos.css +++ b/_static/pyos.css @@ -69,7 +69,7 @@ h1 { color: var(--pyos-h1-color); } h2 { - margin-top: 80px; + margin-top: 1em; } h3 { diff --git a/index.md b/index.md index 8ad72bcf..646f2d3c 100644 --- a/index.md +++ b/index.md @@ -56,7 +56,7 @@ Community docs Publish your docs ``` -## _new_ Tutorial Series: How to Create a Python Package +## _new_ Tutorial Series The how to create a Python package tutorial series is being developed by the community now! Join our community review process or watch development of these tutorials in our [Github repo here](https://github.com/pyOpenSci/python-package-guide). @@ -100,7 +100,7 @@ by the community now! Join our community review process or watch development of ::::: -## Python packaging ecosystem overview & best practices +## Packaging Learn about Python packaging best practices. You will also get to know the the vibrant ecosystem of packaging tools that are available to help you with your Python packaging needs. @@ -135,7 +135,13 @@ Learn about best practices for: ::: :::: +::::: + +## Documentation +:::::{grid} 1 1 2 2 +:class-container: text-center +:gutter: 3 ::::{grid-item} :::{card} ✨ Write & Publish Docs ✨ @@ -160,6 +166,14 @@ Learn about best practices for: *We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)* ::: :::: +::::: + +## Contributing + +:::::{grid} 1 1 2 2 +:class-container: text-center +:gutter: 3 + ::::{grid-item} :::{card} ✨ Code style & Format ✨ @@ -228,20 +242,19 @@ This is a living guide that is updated as tools and best practices evolve in the Tutorials ``` - ```{toctree} :hidden: -:caption: Documentation +:caption: Packaging -Documentation +Packaging ``` ```{toctree} :hidden: -:caption: Packaging +:caption: Documentation -Packaging +Documentation ``` From e0f3fdb92bf452654ad0ae7f2e19684e139a79c2 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 27 Feb 2024 13:12:31 -0800 Subject: [PATCH 02/10] make more links to documentation and tests sections --- index.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/index.md b/index.md index 646f2d3c..8c0ce104 100644 --- a/index.md +++ b/index.md @@ -144,15 +144,55 @@ Learn about best practices for: :gutter: 3 ::::{grid-item} -:::{card} ✨ Write & Publish Docs ✨ +:::{card} ✨ Write The Docs ✨ :class-card: left-aligned * [Create documentation for your users](/documentation/write-user-documentation/intro) * [Core files to include in your package repository](/documentation/repository-files/intro) +* [Write tutorials to show how your package is used](/documentation/write-user-documentation/create-package-tutorials) +::: +:::: + +::::{grid-item} +:::{card} ✨ Developer Docs ✨ +:class-card: left-aligned + +* [Create documentation for collaborating developers](/documentation/repository-files/contributing-file) +* [Write a development guide](/documentation/repository-files/development-guide) +::: +:::: + +::::{grid-item} +:::{card} ✨ Document For A Community ✨ +:class-card: left-aligned + +* [Writing a README file](/documentation/repository-files/readme-file-best-practices) +* [Set norms with a Code of Conduct](/documentation/repository-files/code-of-conduct) +* [License your package](/documentation/repository-files/license-files) +::: +:::: + +::::{grid-item} +:::{card} ✨ Publish Your Docs ✨ +:class-card: left-aligned + * [How to publish your docs](/documentation/hosting-tools/intro) +* [Using Sphinx](/documentation/hosting-tools/intro) +* [Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-rst-doc-syntax) +* [Host your docs on Read The Docs or Github Pages](/documentation/hosting-tools/publish-documentation-online) ::: :::: +::::: + +## Tests + +*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)* + +:::::{grid} 1 1 2 2 +:class-container: text-center +:gutter: 3 + ::::{grid-item} :::{card} ✨ Tests for your Python package ✨ :class-card: left-aligned @@ -160,10 +200,15 @@ Learn about best practices for: * [Intro to testing](tests/index.md) * [Write tests](tests/write-tests) * [Types of tests](tests/test-types) +::: +:::: + +::::{grid-item} +:::{card} ✨ Run your tests ✨ +:class-card: left-aligned + * [Run tests locally](tests/run-tests) * [Run tests in CI](tests/tests-ci) - -*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)* ::: :::: ::::: From 30fdd2ae796fd11f743e77070f087bd1afbab541 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 19 Mar 2024 15:14:24 -0700 Subject: [PATCH 03/10] remove pyproject --- noxfile.py | 4 ++-- pyproject.toml | 19 +++++++++++++++---- requirements.txt | 14 -------------- 3 files changed, 17 insertions(+), 20 deletions(-) delete mode 100644 requirements.txt diff --git a/noxfile.py b/noxfile.py index 62324af6..21e9dc3e 100644 --- a/noxfile.py +++ b/noxfile.py @@ -11,7 +11,7 @@ @nox.session def docs(session): - session.install("-r", "requirements.txt") + session.install("-e", ".") cmd = ["sphinx-build"] cmd.extend(build_command + session.posargs) session.run(*cmd) @@ -19,7 +19,7 @@ def docs(session): @nox.session(name="docs-live") def docs_live(session): - session.install("-r", "requirements.txt") + session.install("-e", ".") AUTOBUILD_IGNORE = [ "_build", diff --git a/pyproject.toml b/pyproject.toml index 1032afa6..f48377a1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,8 +1,13 @@ +[build-system] +requires = ["hatchling", "hatch-vcs"] +build-backend = "hatchling.build" + [project] name = "python-package-guide" - -[project.optional.dependencies] -dev = [ +dynamic = [ + "version" +] +dependencies = [ "pydata-sphinx-theme==0.15.1", "myst-nb", "sphinx", @@ -17,7 +22,13 @@ dev = [ "sphinx-inline-tabs", # for project cards "matplotlib" - ] +] + +[tool.hatch.build.targets.wheel] +bypass-selection = true + +[tool.hatch] +version.source = "vcs" # https://github.com/codespell-project/codespell#usage diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 5d60e172..00000000 --- a/requirements.txt +++ /dev/null @@ -1,14 +0,0 @@ -pydata-sphinx-theme==0.14.4 -myst-nb -sphinx -sphinx-autobuild -sphinx-copybutton -sphinx-design -sphinx-favicon -# XML feed for analytics -sphinx-sitemap -# Support for social / adds meta tags -sphinxext-opengraph -sphinx-inline-tabs -# for project cards -matplotlib From aa2dba2bfbd8ca8cfed3b6dddb90e3fe79a75a2b Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 19 Mar 2024 15:26:41 -0700 Subject: [PATCH 04/10] docs-test --- .github/workflows/build-book.yml | 2 +- noxfile.py | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-book.yml b/.github/workflows/build-book.yml index 740515ed..8a8df52d 100644 --- a/.github/workflows/build-book.yml +++ b/.github/workflows/build-book.yml @@ -42,7 +42,7 @@ jobs: run: python3 -m pip install nox - name: Build book - run: nox -s docs + run: nox -s docs-test # Save html as artifact - name: Save book html as artifact for viewing diff --git a/noxfile.py b/noxfile.py index 62324af6..6af652e9 100644 --- a/noxfile.py +++ b/noxfile.py @@ -16,6 +16,17 @@ def docs(session): cmd.extend(build_command + session.posargs) session.run(*cmd) +@nox.session(name="docs-test") +def docs_test(session): + """ + Same as `docs`, but rebuild everything and fail on warnings for testing + """ + session.install("-r", "requirements.txt") + cmd = ["sphinx-build"] + cmd.extend(['-W', '--keep-going', '-E', '-a']) + cmd.extend(build_command + session.posargs) + session.run(*cmd) + @nox.session(name="docs-live") def docs_live(session): From c0da378eb6803e77165a162ec1bf43291a80d8a7 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 19 Mar 2024 15:54:46 -0700 Subject: [PATCH 05/10] fix errors --- CONTRIBUTING.md | 3 +++ conf.py | 1 + tutorials/add-license-coc.md | 3 +-- tutorials/installable-code.md | 2 -- tutorials/publish-conda-forge.md | 6 +++--- 5 files changed, 8 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3817ab9..bf26b027 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,6 @@ +--- +orphan: true +--- # Contributing Guide for the Python open source software packaging book This is a community resource. We welcome contributions in the form of issues and/or pull requests to this guide. diff --git a/conf.py b/conf.py index 5f6a0e76..f4498c49 100644 --- a/conf.py +++ b/conf.py @@ -61,6 +61,7 @@ "attrs_block", ] myst_heading_anchors = 3 +myst_footnote_transition = False # Sphinx_favicon is used now in favor of built in support # https://pypi.org/project/sphinx-favicon/ diff --git a/tutorials/add-license-coc.md b/tutorials/add-license-coc.md index af1fc952..bd0177fa 100644 --- a/tutorials/add-license-coc.md +++ b/tutorials/add-license-coc.md @@ -170,13 +170,12 @@ The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, That's it - you've now added a code of conduct to your package directory. :::{admonition} Additional Code of Conduct resources -:class: note - [ Guide: `CODE_OF_CONDUCT.md` files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) - [pyOpenSci package guide `CODE_OF_CONDUCT.md` overview](https://www.pyopensci.org/python-package-guide/documentation/repository-files/code-of-conduct-file.html) - ::: + ## Wrap up In this lesson and the [last lesson](add-readme), you have added a: diff --git a/tutorials/installable-code.md b/tutorials/installable-code.md index 6c25d42b..9b1372ba 100644 --- a/tutorials/installable-code.md +++ b/tutorials/installable-code.md @@ -587,9 +587,7 @@ Type "help", "copyright", "credits" or "license" for more information. 3 ``` - :::{admonition} Installing packages from GitHub - If you wish to share your code without publishing to PyPI you can always install packages directly from GitHub using the syntax: diff --git a/tutorials/publish-conda-forge.md b/tutorials/publish-conda-forge.md index 5eedb4ef..289c0e34 100644 --- a/tutorials/publish-conda-forge.md +++ b/tutorials/publish-conda-forge.md @@ -44,7 +44,7 @@ Anyone can submit a package to these channels however they must pass a technical [Learn more about conda channels here.](#about-conda) -:::{figure-md} pypi-conda-channels +:::{figure-md} pypi-conda-channels-2 Graphic with the title Python package repositories. Below it says anything hosted on PyPI can be installed using pip install. Packaging hosted on a conda channel can be installed using conda install. Below that there are two rows. The top row says conda channels. Next to it are three boxes one with conda-forge, community maintained; bioconda and then default - managed by the Anaconda team. Below that there is a row that says PyPI servers. PyPI - anyone can publish to PyPI and test PyPI (a testbed server for you to practice). @@ -228,7 +228,7 @@ where it saved the recipe file. Open the meta.yaml file. The finished `meta.yaml` file that grayskull creates should look like the example below: -```yaml +```yaml+jinja {% set name = "pyospackage" %} {% set version = "0.1.8" %} @@ -421,7 +421,7 @@ This is also why we don't suggest you publish to conda-forge as a practice run. Once you create your pull request, a suite of CI actions will run that build and test the build of your package. A conda-forge maintainer will work with you to get your recipe in good shape and merged. -:::{figure-md} pypi-conda-channels +:::{figure-md} conda-forge-pr-build Image showing the 5 CI tasks that will run against your package in the GitHub interface after you'ce created a pull request. From def1779d64f55fe4689cd54f60f0ae7bb338efe2 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 19 Mar 2024 15:58:17 -0700 Subject: [PATCH 06/10] undo stuff from trying to bughunt footer separators --- tutorials/add-license-coc.md | 2 +- tutorials/installable-code.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/tutorials/add-license-coc.md b/tutorials/add-license-coc.md index bd0177fa..2e8f6ebc 100644 --- a/tutorials/add-license-coc.md +++ b/tutorials/add-license-coc.md @@ -170,12 +170,12 @@ The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, That's it - you've now added a code of conduct to your package directory. :::{admonition} Additional Code of Conduct resources +:class: note - [ Guide: `CODE_OF_CONDUCT.md` files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) - [pyOpenSci package guide `CODE_OF_CONDUCT.md` overview](https://www.pyopensci.org/python-package-guide/documentation/repository-files/code-of-conduct-file.html) ::: - ## Wrap up In this lesson and the [last lesson](add-readme), you have added a: diff --git a/tutorials/installable-code.md b/tutorials/installable-code.md index 9b1372ba..6c25d42b 100644 --- a/tutorials/installable-code.md +++ b/tutorials/installable-code.md @@ -587,7 +587,9 @@ Type "help", "copyright", "credits" or "license" for more information. 3 ``` + :::{admonition} Installing packages from GitHub + If you wish to share your code without publishing to PyPI you can always install packages directly from GitHub using the syntax: From 3ebfadf3568269079ce415d96a38aeb680d785f6 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 19 Mar 2024 16:06:12 -0700 Subject: [PATCH 07/10] fix code of conduct link --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 24c4a791..0616b506 100644 --- a/index.md +++ b/index.md @@ -167,7 +167,7 @@ Learn about best practices for: :class-card: left-aligned * [Writing a README file](/documentation/repository-files/readme-file-best-practices) -* [Set norms with a Code of Conduct](/documentation/repository-files/code-of-conduct) +* [Set norms with a Code of Conduct](/documentation/repository-files/code-of-conduct-file) * [License your package](/documentation/repository-files/license-files) ::: :::: From 10213bfd91be26981f554dbd165c089ac4c37bc9 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 20 Mar 2024 09:44:35 -0600 Subject: [PATCH 08/10] Fix: minor edits --- index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/index.md b/index.md index 0616b506..76384287 100644 --- a/index.md +++ b/index.md @@ -56,10 +56,9 @@ Community docs Publish your docs ``` -## _new_ Tutorial Series +## _new_ Tutorial Series: Create a Python Package -The how to create a Python package tutorial series is being developed -by the community now! Join our community review process or watch development of these tutorials in our [Github repo here](https://github.com/pyOpenSci/python-package-guide). +The first round of our community-developed, how to create a Python package tutorial series for scientists is complete! Join our community review process or watch development of future tutorials in our [Github repo here](https://github.com/pyOpenSci/python-package-guide). :::::{grid} 1 1 2 2 @@ -100,7 +99,7 @@ by the community now! Join our community review process or watch development of ::::: -## Packaging +## Python Packaging for Scientists Learn about Python packaging best practices. You will also get to know the the vibrant ecosystem of packaging tools that are available to help you with your Python packaging needs. From fccdef138c7994fda7dc7cfd5d235f1f83f12190 Mon Sep 17 00:00:00 2001 From: "allcontributors[bot]" <46447321+allcontributors[bot]@users.noreply.github.com> Date: Wed, 20 Mar 2024 15:15:03 -0600 Subject: [PATCH 09/10] docs: add ctb as a contributor for code, and review (#208) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> --- .all-contributorsrc | 10 ++++++++++ README.md | 3 ++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index 00b1dc45..595b367d 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -472,6 +472,16 @@ "review", "tutorial" ] + }, + { + "login": "ctb", + "name": "C. Titus Brown", + "avatar_url": "https://avatars.githubusercontent.com/u/51016?v=4", + "profile": "http://ivory.idyll.org/blog/", + "contributions": [ + "code", + "review" + ] } ], "contributorsPerLine": 7, diff --git a/README.md b/README.md index 20d7ae97..e088aef4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # pyOpenSci scientific Python Packaging Guide -[![All Contributors](https://img.shields.io/badge/all_contributors-45-orange.svg?style=flat-square)](#contributors-) +[![All Contributors](https://img.shields.io/badge/all_contributors-46-orange.svg?style=flat-square)](#contributors-) ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic) @@ -132,6 +132,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d h-vetinari
h-vetinari
💻 👀 ✅ Ivan Ogasawara
Ivan Ogasawara
💻 👀 ✅ Tom Russell
Tom Russell
💻 👀 ✅ + C. Titus Brown
C. Titus Brown
💻 👀 From 978d00d1bb3906b6db0b20a52cd4a91aa47183c6 Mon Sep 17 00:00:00 2001 From: Jonny Saunders Date: Wed, 20 Mar 2024 14:19:06 -0700 Subject: [PATCH 10/10] Update noxfile.py (#207) --- noxfile.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index d9c08bf0..7ba28129 100644 --- a/noxfile.py +++ b/noxfile.py @@ -21,7 +21,7 @@ def docs_test(session): """ Same as `docs`, but rebuild everything and fail on warnings for testing """ - session.install("-r", "requirements.txt") + session.install("-e", ".") cmd = ["sphinx-build"] cmd.extend(['-W', '--keep-going', '-E', '-a']) cmd.extend(build_command + session.posargs)