diff --git a/index.md b/index.md index b3c17a62..c10d2759 100644 --- a/index.md +++ b/index.md @@ -64,8 +64,7 @@ The first round of our community-developed, how to create a Python package tutor :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✿ Create a Package Tutorials ✿ +::::{grid-item-card} ✿ Create a Package Tutorials ✿ :class-card: left-aligned * [What is a Python package?](/tutorials/intro) @@ -73,36 +72,29 @@ The first round of our community-developed, how to create a Python package tutor * [Publish your package to (test) PyPI](/tutorials/publish-pypi) * [Publish your package to conda-forge](/tutorials/publish-conda-forge) -::: :::: -::::{grid-item} -:::{card} ✿ Package Metadata Tutorials ✿ +::::{grid-item-card} ✿ Package Metadata Tutorials ✿ :class-card: left-aligned * [How to add a README file](/tutorials/add-readme) * [How to add metadata to a pyproject.toml file for publication to PyPI.](/tutorials/pyproject-toml.md) -::: :::: -::::{grid-item} -:::{card} ✿ Packaging Tool Tutorials ✿ +::::{grid-item-card} ✿ Packaging Tool Tutorials ✿ :class-card: left-aligned * [Introduction to Hatch](/tutorials/get-to-know-hatch) * [Run Python scripts using Hatch](/tutorials/run-python-scripts-hatch) -::: :::: -::::{grid-item} -:::{card} ✿ Reference Guides ✿ +::::{grid-item-card} ✿ Reference Guides ✿ :class-card: left-aligned * [Command Line Reference Guide](/tutorials/command-line-reference) -::: :::: ::::: @@ -116,8 +108,7 @@ the vibrant ecosystem of packaging tools that are available to help you with you :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Create your package ✨ +::::{grid-item-card} ✨ Create your package ✨ :class-card: left-aligned * [Package file structure](/package-structure-code/python-package-structure) @@ -127,11 +118,9 @@ the vibrant ecosystem of packaging tools that are available to help you with you * [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} -:::{card} ✨ Publish your package ✨ +::::{grid-item-card} ✨ Publish your package ✨ :class-card: left-aligned Gain a better understanding of the Python packaging ecosystem @@ -140,7 +129,6 @@ Learn about best practices for: * [Package versioning & release](/package-structure-code/python-package-versions.md) * [Publish to PyPI & Conda-forge](/package-structure-code/publish-python-package-pypi-conda.md) -::: :::: ::::: @@ -150,44 +138,36 @@ Learn about best practices for: :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Write The Docs ✨ +::::{grid-item-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 ✨ +::::{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 ✨ +::::{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-file) * [License your package](/documentation/repository-files/license-files) -::: :::: -::::{grid-item} -:::{card} ✨ Publish Your Docs ✨ +::::{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) -::: :::: ::::: @@ -198,24 +178,20 @@ Learn about best practices for: :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Tests for your Python package ✨ +::::{grid-item-card} ✨ Tests for your Python package ✨ :class-card: left-aligned * [Intro to testing](tests/index.md) * [Write tests](tests/write-tests) * [Types of tests](tests/test-types) -::: :::: -::::{grid-item} -:::{card} ✨ Run your tests ✨ +::::{grid-item-card} ✨ Run your tests ✨ :class-card: left-aligned * [Run tests locally with Hatch](tests/run-tests) * [Run tests with nox](tests/run-tests-nox) * [Run tests in CI](tests/tests-ci) -::: :::: ::::: @@ -225,23 +201,19 @@ Learn about best practices for: :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Code style & Format ✨ +::::{grid-item-card} ✨ Code style & Format ✨ :class-card: left-aligned * [Code style](package-structure-code/code-style-linting-format.md) -::: :::: -::::{grid-item} -:::{card} ✨ Want to contribute? ✨ +::::{grid-item-card} ✨ Want to contribute? ✨ :link: CONTRIBUTING :link-type: doc :class-card: left-aligned We welcome contributions to this guide. Learn more about how you can contribute. -::: :::: ::::: diff --git a/package-structure-code/intro.md b/package-structure-code/intro.md index 6d1e513d..80912931 100644 --- a/package-structure-code/intro.md +++ b/package-structure-code/intro.md @@ -5,8 +5,7 @@ This section covers everything you need to structure your Python package, config :::::{grid} 1 1 2 2 :gutter: 3 -::::{grid-item} -:::{card} New to Python packaging? +::::{grid-item-card} New to Python packaging? :class-card: sd-shadow-sm **Start with our step-by-step tutorials:** @@ -22,11 +21,9 @@ This section covers everything you need to structure your Python package, config Start the tutorial series ``` -::: :::: -::::{grid-item} -:::{card} Already have code to package? +::::{grid-item-card} Already have code to package? :class-card: sd-shadow-sm **Jump into the reference guides:** @@ -36,7 +33,6 @@ Start the tutorial series - Understand the publishing process Start with the cards below ↓ -::: :::: ::::: @@ -66,34 +62,26 @@ Our recommendations align with current [Python packaging standards](https://pack :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Package file structure ✨ +::::{grid-item-card} ✨ Package file structure ✨ Learn how to organize your package files using [src or flat layouts](package-source-layout). This page helps you decide on a package structure that follows modern Python best practices, including where to place [tests](src-layout-test) and [documentation](package-source-layout). -::: :::: -::::{grid-item} -:::{card} ✨ Add metadata ✨ +::::{grid-item-card} ✨ Add metadata ✨ Learn how to add [project metadata](pyproject-toml-python-package-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} ✨ Declare dependencies ✨ +::::{grid-item-card} ✨ Declare dependencies ✨ Learn how to specify [required dependencies](required-dependencies), [optional feature dependencies](optional-dependencies), and [development dependencies](dependency-groups) in your [pyproject.toml file](pyproject-toml-overview). -::: :::: -::::{grid-item} -:::{card} ✨ Setup package versioning ✨ +::::{grid-item-card} ✨ Setup package versioning ✨ Learn how to manage package versions using [semantic versioning (SemVer)](package-versioning) or [calendar versioning (CalVer)](package-versioning). This page helps you choose the right versioning strategy and set up [automated version management](tools-version-management) using tools like hatch_vcs or setuptools-scm. -::: :::: ::::: @@ -104,11 +92,9 @@ Learn how to manage package versions using [semantic versioning (SemVer)](packag :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Code style & linters ✨ +::::{grid-item-card} ✨ Code style & linters ✨ Learn how to set up [code formatters and linters](code-style-tools) ([Black](about-black), [Ruff](about-ruff), [flake8](about-flake8)) to ensure your package follows [PEP 8 standards](code-style-tools) and maintains consistent code style throughout your project. -::: :::: ::::: @@ -119,25 +105,19 @@ Learn how to set up [code formatters and linters](code-style-tools) ([Black](abo :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Choose your build tool ✨ +::::{grid-item-card} ✨ Choose your build tool ✨ Learn how to choose the right packaging tool for your project. Compare [Hatch](about-hatch), [PDM](about-pdm), [Poetry](about-poetry), and [setuptools](about-setuptools) to find the best fit for your workflow. See the [summary comparison](summary-build-tools) to help decide. -::: :::: -::::{grid-item} -:::{card} ✨ Build your package ✨ +::::{grid-item-card} ✨ Build your package ✨ Learn how to build your Python package into [distribution files](build-package) ([sdist](python-source-distribution) and [wheel](python-wheel)) that can be published on [PyPI](publish-pypi-conda). -::: :::: -::::{grid-item} -:::{card} ✨ Publish to PyPI and Conda ✨ +::::{grid-item-card} ✨ Publish to PyPI and Conda ✨ Learn how to publish your package to [PyPI](publish-pypi-conda) and optionally to [conda-forge](how-to-submit-to-conda-forge). This page covers the complete process for making your package available to users, including the [conda-forge submission process](how-to-submit-to-conda-forge) after publishing to PyPI. -::: :::: ::::: diff --git a/tests/index.md b/tests/index.md index 4e758662..d611b213 100644 --- a/tests/index.md +++ b/tests/index.md @@ -12,69 +12,57 @@ to run your tests both [locally](run-tests) and [on GitHub](tests-ci). :class-container: text-center :gutter: 3 -::::{grid-item} -:::{card} ✨ Why write tests ✨ +::::{grid-item-card} ✨ Why write tests ✨ :link: write-tests :link-type: doc :class-card: left-aligned Learn about the importance of writing tests for your Python package and how they help you and potential contributors. -::: :::: -::::{grid-item} -:::{card} ✨ Types of tests ✨ +::::{grid-item-card} ✨ Types of tests ✨ :link: test-types :link-type: doc :class-card: left-aligned Get to know the three test types: unit, integration, and end-to-end tests. Learn when and how to use each. -::: :::: -::::{grid-item} -:::{card} ✨ Run tests locally ✨ +::::{grid-item-card} ✨ Run tests locally ✨ :link: run-tests :link-type: doc :class-card: left-aligned Learn about testing tools like pytest, nox, and tox to run tests across different Python versions on your computer. And explore examples of using Hatch with UV as a task runner to run tests across Python versions. -::: :::: -::::{grid-item} -:::{card} ✨ Run tests locally (using nox) ✨ +::::{grid-item-card} ✨ Run tests locally (using nox) ✨ :link: run-tests-nox :link-type: doc :class-card: left-aligned Nox is a python powered task runner that can be used to run tests. Learn how to use nox to run tests. -::: :::: -::::{grid-item} -:::{card} ✨ Run tests online (using CI) ✨ +::::{grid-item-card} ✨ Run tests online (using CI) ✨ :link: tests-ci :link-type: doc :class-card: left-aligned Set up continuous integration with GitHub Actions to run tests across Python versions and operating systems. -::: :::: -::::{grid-item} -:::{card} ✨ Code coverage ✨ +::::{grid-item-card} ✨ Code coverage ✨ :link: code-cov :link-type: doc :class-card: left-aligned Measure how much of your package code runs during tests. Learn to generate local reports and visualize coverage online. -::: :::: :::::