diff --git a/_static/fonts/poppins-v20-latin-500.woff2 b/_static/fonts/poppins-v20-latin-500.woff2 new file mode 100644 index 00000000..c6603368 Binary files /dev/null and b/_static/fonts/poppins-v20-latin-500.woff2 differ diff --git a/_static/fonts/poppins-v20-latin-600.woff2 b/_static/fonts/poppins-v20-latin-600.woff2 new file mode 100644 index 00000000..921e962b Binary files /dev/null and b/_static/fonts/poppins-v20-latin-600.woff2 differ diff --git a/_static/pyos.css b/_static/pyos.css index b47b9ec2..5ae6506b 100644 --- a/_static/pyos.css +++ b/_static/pyos.css @@ -17,6 +17,13 @@ } + +/* anything related to the dark theme */ +html[data-theme="dark"] { + --pst-color-info-bg: #400f59!important; +} + + html, body { font-size: 1.0rem; } @@ -248,3 +255,47 @@ html[data-theme=dark] { font-weight: 400; src: url('./fonts/itim-v14-latin-regular.woff2') format('woff2'); /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ } + +/* poppins-500 - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Poppins'; + font-style: normal; + font-weight: 500; + src: url('./fonts/poppins-v20-latin-500.woff2') format('woff2'); /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + } + /* poppins-600 - latin */ + @font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Poppins'; + font-style: normal; + font-weight: 600; + src: url('./fonts/poppins-v20-latin-600.woff2') format('woff2'); /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + } +/* Cards */ + +/* todo light and dark adaptations needed */ + +.sd-card-title { + margin-bottom: 0.5rem; + background-color: var(--pst-color-info-bg)!important; + padding: .5rem; + border-bottom: 2px solid #999; + font-size: 1.2rem; + font-weight: 600!important; +} + +.sd-card-header { + font-size: 1.2em; + font-weight: 600; +} + +.sd-card-body { + padding: 0 0!important; + + + .left-aligned + & ul li { + text-align: left; + } +} diff --git a/conf.py b/conf.py index 37e86eea..c7e1db43 100644 --- a/conf.py +++ b/conf.py @@ -58,7 +58,7 @@ "href": "https://www.pyopensci.org/images/favicon.ico", }, ], - "announcement": "

Submit Your Python Package for Peer Review - Learn More!

🚧 This guide is currently being developed! 🚧 ", + "announcement": "

We run peer review of scientific Python software. Learn more.

", #"navbar_center": ["nav"], this can be a way to override the default navigation structure "external_links": [ { @@ -82,12 +82,12 @@ }, ], "logo": { - "text": "Python Packaging", + #"text": "Python Packaging", "image_dark": "logo-dark-mode.png", "image_light": "logo-light-mode.png", "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is a purple flower with pyOpenSci under it. The o in open sci is the center of the flower", }, - "header_links_before_dropdown": 4, + "header_links_before_dropdown": 3, "use_edit_page_button": True, "show_nav_level": 2, "navigation_depth": 3, diff --git a/documentation/index.md b/documentation/index.md index 23d1aa71..2646f0e5 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -20,21 +20,30 @@ Create Package Tutorials ```{toctree} :hidden: -:caption: Core Repository Files +:caption: Docs for Contributors & Maintainers :maxdepth: 2 Intro -README file + Contributing File -Code of Conduct File + Development Guide +``` + +```{toctree} +:hidden: +:caption: Community Docs +:maxdepth: 2 + +README file +Code of Conduct File LICENSE files ``` ```{toctree} :maxdepth: 2 :hidden: -:caption: Documentation & Hosting Tools +:caption: Publication tools for your docs Intro Sphinx for Docs diff --git a/images/tutorials/packaging-elements.png b/images/tutorials/packaging-elements.png new file mode 100644 index 00000000..712c7738 Binary files /dev/null and b/images/tutorials/packaging-elements.png differ diff --git a/index.md b/index.md index 164a3bec..b3af65e1 100644 --- a/index.md +++ b/index.md @@ -1,186 +1,191 @@ -# pyOpenSci Python Open Source Package Development Guide +# pyOpenSci Python Package Guide -```{toctree} -:hidden: -:caption: Documentation +We support the Python tools that scientists need to create open science workflows. -Documentation +::::{grid} 2 +:reverse: -``` +:::{grid-item} +:columns: 4 +:class: sd-m-auto -```{toctree} -:hidden: -:caption: Packaging +::: -Packaging +:::{grid-item} +:columns: 8 +:class: sd-fs-3 +```{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) +[![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/contributing-guide) +[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582) ``` -```{toctree} -:hidden: -:caption: CI and Testing +::: +:::: -CI & Tests -``` +::::{admonition} About this guide - +:::{image} /images/tutorials/packaging-elements.png +:align: right +:width: 500 +:alt: Image with the pyOpenSci flower logo in the upper right hand corner. The image shows the packaging lifecycle. The graphic shows a high level overview of the elements of a Python package. the inside circle has 5 items - user documentation, code/api, test suite, contributor documentation, project metadata / license / readme. In the middle of the circle is says maintainers and has a small icon with people. on the outside circle there is an arrow and it says infrastructure. +::: -## Welcome, Python open source enthusiast! +This guide will help you: -Here you will find guidelines for what we look for in your scientific -Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and package documentation. +1. Learn how to create a Python package from start to finish +1. Understand the broader Python packaging tool ecosystem +1. Navigate and make decisions around tool options +1. Understand all of the pieces of creating and maintaining a Python package -### pyOpenSci's packaging goals +You will also find best practice recommendations and curated lists of community resources surrounding packaging and package documentation. +:::: -Our goal is to help the -community make decisions around how to create scientific Python packages. We are working towards a shared vision of packaging that helps users better understand where to start. -### How this guide is created +```{todo} +TODO: change the navigation of docs to have a -This guide is created by pyOpenSci through an extensive review process. Each page in the guide has been reviewed by experts in the broader Python packaging landscape including people from : +user documentation +contributor / maintainer documentation +* development guide +* contributing guide -- conda & conda-forge -- the python packaging authority -- core Python developers -- core scientific Python developers -- and others with expertise in packaging, package documentation, usability and other related knowledge areas +Community docs +* readme, coc, license -[View all of the people who have contributed to this guide here. -](https://github.com/pyOpenSci/python-package-guide#contributors-) +Publish your docs +``` -We use this guide as a foundation for our open peer review process of -scientific software. +## Python packaging ecosystem overview & best practices -::::{grid} 2 -:reverse: +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. -:::{grid-item} -:columns: 4 -:class: sd-m-auto +:::::{grid} 1 1 2 2 +:class-container: text-center +:gutter: 3 + +::::{grid-item} +:::{card} ✨ Create your package ✨ +:class-card: left-aligned + +* [Package file structure](/package-structure-code/python-package-structure) +* [Package metadata / pyproject.toml](package-structure-code/pyproject-toml-python-package-metadata.md) +* [Build your package (sdist / wheel)](package-structure-code/python-package-distribution-files-sdist-wheel.md) +* [Declare dependencies](package-structure-code/declare-dependencies.md) +* [Navigate the packaging tool ecosystem](package-structure-code/python-package-build-tools.md) +* [Non pure Python builds](package-structure-code/complex-python-package-builds.md) ::: +:::: -:::{grid-item} -:columns: 8 -:class: sd-fs-3 +::::{grid-item} +:::{card} ✨ Publish your package ✨ +:class-card: left-aligned -```{button-link} https://www.pyopensci.org/about-peer-review/ -:color: primary -:class: sd-rounded-pill float-left -Learn about our open peer review process -``` +Gain a better understanding of the Python packaging ecosystem +Learn about best practices for: -```{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) -[![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/contributing-guide) -[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582) -``` +* [Package versioning & release](/package-structure-code/python-package-versions.md) +* [Publish to PyPI & Conda-forge](/package-structure-code/publish-python-package-pypi-conda.md) ::: :::: - - -::::{grid} 1 1 2 2 -:class-container: text-center -:gutter: 3 - -:::{grid-item-card} -:link: documentation/index -:link-type: doc -✨ Documentation Criteria & Recommendations ✨ -^^^ +::::{grid-item} +:::{card} ✨ Write & Publish Docs ✨ +:class-card: left-aligned -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. +* [Create documentation for your users](/documentation/write-user-documentation/intro) +* [Core files to include in your package repository](/documentation/repository-files/intro) +* [How to publish your docs](/documentation/hosting-tools/intro) ::: +:::: -:::{grid-item-card} -:link: package-structure-code/intro -:link-type: doc +::::{grid-item} +:::{card} ✨ Tests, checks & clean code ✨ +:class-card: left-aligned + +* [Code style](package-structure-code/code-style-linting-format.md) -✨ Python packaging tools & structure ✨ -^^^ -All of the modern tools discussed in this guide will help you build an efficient packaging workflow. This section helps you select the tool that will work best for you. +*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)* ::: +:::: -:::{grid-item-card} +::::{grid-item} +:::{card} ✨ Want to contribute? ✨ :link: CONTRIBUTING :link-type: doc +:class-card: left-aligned -✨ Want to contribute? ✨ -^^^ We welcome contributions to this guide. Learn more about how you can contribute. ::: :::: -## Who this guidebook is for +::::: + + +:::{figure} https://www.pyopensci.org/images/people-building-blocks.jpg +:align: right +:width: 350 +:alt: xkcd comic showing a stick figure on the ground and one in the air. The one on the ground is saying. `You're flying! how?` The person in the air replies `Python!` Below is a 3 rectangle comic with the following text in each box. box 1 - I learned it last night. Everything is so simple. Hello world is just print hello world. box 2 - the person on the ground says - come join us programming is fun again. it's a whole new world. But how are you flying? box 3 - the person flying says - i just typed import antigravity. I also sampled everything in the medicine cabinet. But i think this is the python. the person on the ground is saying - that's it? +::: -We assume that you are here because you are: +### A community-created guidebook -1. Looking for guidance on creating a Python package. -1. Looking for resources associated with Python packaging. -1. Considering submitting a package to pyOpenSci and want to understand what we are looking for when we review your package +Every page in this guidebook goes through an extensive community review +process. To ensure our guidebook is both beginner-friendly and accurate, we encourage reviews from a diverse set of pythonistas and scientists with a wide range of skills and expertise. -Well, friend, you've come to the right place! +```{button-link} https://github.com/pyOpenSci/python-package-guide#contributors- +:color: primary +:class: sd-rounded-pill float-left +View guidebook contributors -:::{figure-md} fig-target +``` -xkcd comic showing a stick figure on the ground and one in the air. The one on the ground is saying. `You're flying! how?` The person in the air replies `Python!` Below is a 3 rectangle comic with the following text in each box. box 1 - I learned it last night. Everything is so simple. Hello world is just print hello world. box 2 - the person on the ground says - come join us programming is fun again. it's a whole new world. But how are you flying? box 3 - the person flying says - i just typed import antigravity. I also sampled everything in the medicine cabinet. But i think this is the python. the person on the ground is saying - that's it? +## Who this guidebook is for -Many love to use Python because it is a clean language to learn. It also is incredibly flexible allowing it to be used across numerous domains. Source: xkcd comics. -::: +This guidebook is for anyone interested in learning more about Python packaging. It is beginner-friendly and will provide: -## What you will find in this guidebook +1. Beginning-to-end guidance on creating a Python package. +1. Resources to help you navigate the Python packaging ecosystem of tools and approaches to packaging. +1. A curated list of resources to help you get your package into documented, usable and maintainable shape. -This guidebook contains: -- Explanation for "Good enough" minimum requirements associated with being reviewed by pyOpenSci -- Explanation of better and best practices in case you want to set the bar higher for your package (which we hope you will)! -- A curated list of resources to help you get your package into documented, usable and tested shape. -## Where this guide is headed -Most of the sections in this guide will ultimately include Good/Better/Best recommendations for Python open source software packaging. +## Where this guide is headed -Good meets the requirements. Going beyond the minimum can make package maintenance easier-to-use for new users, easier-to contribute for new contributors and easier-to-maintain for you. +If you have ideas of things you'd like +to see here clarified in this guide, [we invite you to open an issue on GitHub.](https://github.com/pyOpenSci/python-package-guide/issues). -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). +If you have questions about our peer review process or packaging in general, you are welcome to use our [pyOpenSci Discourse forum](https://pyopensci.discourse.group/). - +CI & Tests +```