Skip to content

Fix: a few fixes to support the new theme and also updated cards #150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 5, 2024
Merged

Fix: a few fixes to support the new theme and also updated cards #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2324b9c
Fix: a few fixes to support the new theme and also updated cards
lwasser Jan 5, 2024
db095ab
Fix: pinning to version 14.4
lwasser Jan 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
"sphinx.ext.todo",
"sphinx_sitemap",
"sphinxext.opengraph",
"sphinx_favicon",
]

# colon fence for card support in md
Expand All @@ -46,16 +47,14 @@
]
myst_heading_anchors = 3

# Sphinx_favicon is used now in favor of built in support
# https://pypi.org/project/sphinx-favicon/
favicons = [
{"href": "https://www.pyopensci.org/images/favicon.ico"},
]

# Link to our repo for easy PR/ editing
html_theme_options = {
"favicons": [
{
"rel": "icon",
"sizes": "16x16",
"href": "https://www.pyopensci.org/images/favicon.ico",
},
],
"announcement": "<p><a href='https://www.pyopensci.org/about-peer-review/index.html'>We run peer review of scientific Python software. Learn more.</a></p>",
#"navbar_center": ["nav"], this can be a way to override the default navigation structure
"external_links": [
Expand Down Expand Up @@ -93,7 +92,8 @@
# "navbar_align": "left", # [left, content, right] For testing that the navbar items align properly
"github_url": "https://github.com/pyopensci/python-package-guide",

"footer_items": ["copyright"],
"footer_start": ["copyright"],
"footer_end": [],
}

html_context = {
Expand Down
57 changes: 5 additions & 52 deletions documentation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Documentation for your Open Source Python Package

```{toctree}
:::{toctree}
:hidden:
:caption: Intro

Documentation Overview <self>
```
:::

```{toctree}
:hidden:
Expand All @@ -24,9 +24,7 @@ Create Package Tutorials <write-user-documentation/create-package-tutorials.md>
:maxdepth: 2

Intro <repository-files/intro.md>

Contributing File <repository-files/contributing-file.md>

Development Guide <repository-files/development-guide.md>
```

Expand Down Expand Up @@ -63,32 +61,6 @@ requirements. Our requirements are focused on the
documentation content of your package.
```

<!-- ```{toctree}
:hidden:

Best Practices for Docs <package-documentation-best-practices>
Tools to Build Your Docs <python-package-documentation-tools>
Host & Help People Find Your Docs <website-hosting-optimizing-your-docs>
The README File <readme-file-best-practices.md>
Contributing & License files <contributing-license-coc>
``` -->
<!--
```{important}
## Quick Takeaways: Documentation must haves

Your package should at a minimum have:
* README.MD file
* CONTRIBUTING.md file
* CODE_OF_CONDUCT.md
* LICENSE.txt
* User-facing documentation website with tutorials
* API documentation (often found in the user-facing documentation website)

The pages in this section of our guide provide you with more
detail about creating each of the above elements. We also suggest
tools that will help you build your documentation.
``` -->

## Documentation is critical for your Python package's success

Documentation is as important to the success of your Python open source package
Expand Down Expand Up @@ -154,25 +126,13 @@ found in our peer review check list (see link below).
In this guide, we discuss each required element, and also discuss other elements
that you should consider in your package's documentation in more detail.

<!-- TODO: EIC checks are missing: code of conduct -->

```{button-link} https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template
:color: primary
:class: sd-rounded-pill float-left
View pyOpenSci peer review check list
```

<!--
1. Individual files in your GitHub (or GitLab) repository including:
* [A clear and to the point **README.md** file](readme-file-best-practices) that includes information about how to cite your package.
* A [**CONTRIBUTING.md** file](contributing-license-coc) 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.
* A [**CODE_OF_CONDUCT.md**](contributing-license-coc.html#the-code-of-conduct-md-file) file. This file sets up the guidelines for how your community interacts. It ideally ensures that everyone feels safe and can report inappropriate behavior if need be.
* [**A LICENSE.txt file**](contributing-license-coc.html#your-repository-should-have-a-license-md-file) A license file declaring the OSI-approved license that you select and instructions for citing your package.
* We also suggest (but don't require) that you include a development guide that details the infrastructure used in your package. Sometimes this file is included in the user-facing documentation website (discussed below).
1. [**User focused package documentation**](package-documentation-best-practices) that helps users understand how to install, setup and use your package. Documentation is most often contained in a stand-alone website. The user-focused documentation should include:
* **Tutorials and quick start code examples** that help a user get started using your package.
* **Documentation for user-facing functions, objects and methods in your package (the API).** Package API documentation refers to documentation for each class, function, method and user-facing attribute (*available for a user to see*) in your package. This means that your package methods and classes should have [thoughtful docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) that describe both the purpose of the code element and each input and output.
-->

```{figure} ../images/moving-pandas-python-package-github-main-repo.png
---
Expand All @@ -190,18 +150,11 @@ you through best practices for setting up
documentation for your Python package. We will also suggest
tools that you can use to build your user-facing documentation website.

<!--
Commenting this out for now - it will be moved to another section
:::{todo}

## Other recommendations
### Python version support
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. -->
:::
3 changes: 1 addition & 2 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,7 @@ process. To ensure our guidebook is both beginner-friendly and accurate, we enco
```{button-link} https://github.com/pyOpenSci/python-package-guide#contributors-
:color: primary
:class: sd-rounded-pill float-left

View guidebook contributors

```
Expand Down Expand Up @@ -217,7 +218,5 @@ Packaging <package-structure-code/intro>
:caption: Testing

Tests <tests/index>
Write tests <tests/write-tests>
Types of tests <tests/test-types>

```
81 changes: 47 additions & 34 deletions package-structure-code/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,72 +9,87 @@ there are some great modern packaging tools that ensure that you're following
best practices. Here, we review tool features and suggest tools that might be
best fitted for your workflow.

::::{grid} 1 1 2 2
:::::{grid} 1 1 2 2
:class-container: text-center
:gutter: 3

:::{grid-item-card}
::::{grid-item}
:::{card} ✨ 1. Package file structure ✨
:link: python-package-structure
:link-type: doc

✨ 1. Package file structure ✨
^^^
src layout, flat layout and where should tests folders live? No matter what your level of packaging knowledge is, this page will help you decide upon a package structure that follows modern python best practices.
:::
::::

:::{grid-item-card}
::::{grid-item}
:::{card} ✨ 2. Learn about building your package ✨
:link: python-package-structure
:link-type: doc

✨ 2. Learn about building your package ✨
^^^
Publishing a Python package is a great way to share your code with scientists to support open science workflow. In order to publish a package, you will need to first build it. The act of "building" refers to the process of placing your package code and
metadata into a format that can be published on PyPI. Once published on PyPI, your users can easily install it locally using pip. Learn more about building a Python package here.
To publish your Python package on PyPI, you will need to first build it. The act
of "building" refers to the process of placing your package code and
metadata into a format that can be published on PyPI. Learn more about building
your Python package.
:::
::::

:::{grid-item-card}
:link: python-package-build-tools

::::{grid-item}
:::{card} ✨ 4. Add metadata ✨
:link: pyproject-toml-python-package-metadata
:link-type: doc

✨ 3. What Python package tool should you use? ✨
^^^
Learn how to add project metadata to your Python package to support both
filtering on PyPI and also the metadata that a package installer needs to
build and install your package.
:::
::::

::::{grid-item}
:::{card} ✨ 3. What Python package tool should you use? ✨
:link: python-package-build-tools
:link-type: doc

Learn more about the suite of packaging tools out there.
And learn which tool might be best for you.
:::
::::

:::{grid-item-card}
::::{grid-item}
:::{card} ✨ 4. Publish to PyPI and Conda ✨
:link: python-package-build-tools
:link-type: doc

✨ 4. Publish your package to PyPI and Conda ✨
^^^
If you have a pure python package, it's a straight forward
If you have a pure Python package, it's a straight forward
process to publish to both PyPI and then a Conda channel such as
conda-forge. Learn more here.
:::
::::

:::{grid-item-card}
::::{grid-item}
:::{card} ✨ 5. Setup package versioning ✨
:link: python-package-versions
:link-type: doc

✨ 5. Setup package versioning ✨
^^^
Semver (numeric versioning) and Calver (versioning using the date) are 2
common ways to version a package. Which one should you pick? Learn more here.
:::
::::

:::{grid-item-card}
::::{grid-item}
:::{card} ✨ 6. Code style & linters ✨
:link: code-style-linting-format
:link-type: doc

✨ 6. Code style & linters ✨
^^^
Black, blue, flake8, Ruff - which tools can help you ensure your
package follows best practices for code format? Learn more about the options and why this is important here.
package follows best practices for code format? Learn more about the options
and why this is important here.
:::
::::

:::::

:::{figure-md} packaging-tools-decision-tree

<img src="../images/python-package-tools-decision-tree.png" alt="Figure showing a decision tree with the various packaging tool front-end and back-end options." width="700px">
Expand All @@ -83,13 +98,13 @@ Diagram showing the various front-end build tools that you can select from.
See the packaging tools page to learn more about each tool.
:::

```{note}
:::{note}
If you are considering submitting a package for peer review, have a look
at the bare-minimum [editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template)
that pyOpenSci performs before a review begins. These checks are useful
to explore for both authors planning to submit a package to us for review
and for anyone who is just getting started with creating a Python package.
```
:::

## What you will learn here

Expand All @@ -111,8 +126,6 @@ In this section of our Python packaging guide, we:

## Guidelines for pyOpenSci's packaging recommendations

<!-- Might belong on the LANDING page for this entire guide?-->

The flexibility of the Python programming language lends itself to a diverse
range of tool options for creating a Python package. Python is so flexible that
it is one of the few languages that can be used to wrap around other languages.
Expand All @@ -135,7 +148,7 @@ Python package. In this guide, we suggest packaging approaches and tools based o
Here, we also try to align our suggestions with the most current, accepted
[Python community](https://packaging.python.org/en/latest/) and [scientific community](https://scientific-python.org/specs/).

```{admonition} Suggestions in this guide are not pyOpenSci review requirements
:::{admonition} Suggestions in this guide are not pyOpenSci review requirements
:class: important

The suggestions for package layout in this section are made with the
Expand All @@ -145,9 +158,9 @@ package to be reviewed and accepted into our pyOpenSci open source ecosystem.
Please check out our [package scope page](https://www.pyopensci.org/software-peer-review/about/package-scope.html)
and [review requirements in our author guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#)
if you are looking for pyOpenSci's Python package review requirements!
```
:::

```{toctree}
:::{toctree}
:hidden:
:caption: Package structure & code style

Expand All @@ -159,14 +172,14 @@ Build Your Package <python-package-distribution-files-sdist-wheel>
Declare dependencies <declare-dependencies>
Package Build Tools <python-package-build-tools>
Complex Builds <complex-python-package-builds>
```
:::

```{toctree}
:::{toctree}
:hidden:
:caption: Publishing a package

Publish with Conda / PyPI <publish-python-package-pypi-conda>
Package versions <python-package-versions>
Code style <code-style-linting-format>

```
:::
10 changes: 7 additions & 3 deletions package-structure-code/pyproject-toml-python-package-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,13 @@ what's missing
5. There is no specific order for tables in the `pyproject.toml` file. However fields need to be placed within the correct table sections. For example `requires =` always need to be associated with the **[build-system]** table.
6. **python-requires**: is important to have in your `pyproject.toml` file as it helps pip install your package.

<!-- Commenting this out given the lessons aren't online yet
we can add this back once tutorials are published
:::


:::::{todo}

when these are published, remove this todo

::::{grid} 2

:::{grid-item}
Expand Down Expand Up @@ -51,7 +54,8 @@ Click here if need help migrating from setup.py/setup.cfg to pyproject.toml
```

:::
:::: -->
::::
:::::

## About the pyproject.toml file

Expand Down
22 changes: 22 additions & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,25 @@
[project]
name = "python-package-guide"

[project.optional.dependencies]
dev = [
"pydata-sphinx-theme==0.15.1",
"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"
]


# https://github.com/codespell-project/codespell#usage
[tool.codespell]
ignore-words = "codespell-ignore.txt"
Expand Down
Loading