From 53e603f64e9372fdbc8fd4dd0a96eff1187a5ff2 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Thu, 2 May 2024 13:50:24 -0500 Subject: [PATCH] docs: polyfactory landing page --- .github/workflows/{ci.yaml => ci.yml} | 0 .../{docs-preview.yaml => docs-preview.yml} | 0 .github/workflows/{docs.yaml => docs.yml} | 0 .../workflows/{pr-title.yaml => pr-title.yml} | 0 .../workflows/{publish.yaml => publish.yml} | 0 README.md | 2 +- docs/PYPI_README.md | 2 +- docs/conf.py | 2 +- docs/getting-started.rst | 42 +++++ docs/index.rst | 157 ++++++++++++++---- 10 files changed, 172 insertions(+), 33 deletions(-) rename .github/workflows/{ci.yaml => ci.yml} (100%) rename .github/workflows/{docs-preview.yaml => docs-preview.yml} (100%) rename .github/workflows/{docs.yaml => docs.yml} (100%) rename .github/workflows/{pr-title.yaml => pr-title.yml} (100%) rename .github/workflows/{publish.yaml => publish.yml} (100%) create mode 100644 docs/getting-started.rst diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yml similarity index 100% rename from .github/workflows/ci.yaml rename to .github/workflows/ci.yml diff --git a/.github/workflows/docs-preview.yaml b/.github/workflows/docs-preview.yml similarity index 100% rename from .github/workflows/docs-preview.yaml rename to .github/workflows/docs-preview.yml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yml similarity index 100% rename from .github/workflows/docs.yaml rename to .github/workflows/docs.yml diff --git a/.github/workflows/pr-title.yaml b/.github/workflows/pr-title.yml similarity index 100% rename from .github/workflows/pr-title.yaml rename to .github/workflows/pr-title.yml diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yml similarity index 100% rename from .github/workflows/publish.yaml rename to .github/workflows/publish.yml diff --git a/README.md b/README.md index 780cbb2f..aad8bfe6 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ | Project | | Status | | --------- | :-- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CI/CD | | [![Publish package](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yaml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yaml) [![ci](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yaml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yaml) [![pages-build-deployment](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment) | +| CI/CD | | [![Publish package](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yml) [![ci](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yml) [![pages-build-deployment](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment) | | Quality | | [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=coverage)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) | | Package | | [![PyPI - Version](https://img.shields.io/pypi/v/polyfactory?labelColor=202235&color=edb641&logo=python&logoColor=edb641)](https://badge.fury.io/py/polyfactory) ![PyPI - Support Python Versions](https://img.shields.io/pypi/pyversions/polyfactory?labelColor=202235&color=edb641&logo=python&logoColor=edb641) ![Pydantic Factories PyPI - Downloads](https://img.shields.io/pypi/dm/pydantic-factories?logo=python&label=Pydantic%20Factories%20downloads&labelColor=202235&color=edb641&logoColor=edb641) ![Polyfactory PyPI - Downloads](https://img.shields.io/pypi/dm/polyfactory?logo=python&label=Polyfactory%20downloads&labelColor=202235&color=edb641&logoColor=edb641) | | Community | | [![Reddit](https://img.shields.io/reddit/subreddit-subscribers/litestarapi?label=r%2FLitestar&logo=reddit&labelColor=202235&color=edb641&logoColor=edb641)](https://reddit.com/r/litestarapi) [![Discord](https://img.shields.io/discord/919193495116337154?labelColor=202235&color=edb641&label=chat%20on%20discord&logo=discord&logoColor=edb641)](https://discord.gg/X3FJqy8d2j) [![Matrix](https://img.shields.io/badge/chat%20on%20Matrix-bridged-202235?labelColor=202235&color=edb641&logo=matrix&logoColor=edb641)](https://matrix.to/#/#litestar:matrix.org) [![Medium](https://img.shields.io/badge/Medium-202235?labelColor=202235&color=edb641&logo=medium&logoColor=edb641)](https://blog.litestar.dev) [![Twitter](https://img.shields.io/twitter/follow/LitestarAPI?labelColor=202235&color=edb641&logo=twitter&logoColor=edb641&style=flat)](https://twitter.com/LitestarAPI) [![Blog](https://img.shields.io/badge/Blog-litestar.dev-202235?logo=blogger&labelColor=202235&color=edb641&logoColor=edb641)](https://blog.litestar.dev) | diff --git a/docs/PYPI_README.md b/docs/PYPI_README.md index ac3ce48a..1ec7c1b1 100644 --- a/docs/PYPI_README.md +++ b/docs/PYPI_README.md @@ -9,7 +9,7 @@ | Project | | Status | | --------- | :-- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CI/CD | | [![Publish package](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yaml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yaml) [![ci](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yaml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yaml) [![pages-build-deployment](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment) | +| CI/CD | | [![Publish package](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yaml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/publish.yaml) [![ci](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yaml/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/ci.yml) [![pages-build-deployment](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/litestar-org/polyfactory/actions/workflows/pages/pages-build-deployment) | | Quality | | [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=coverage)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) | | Package | | [![PyPI - Version](https://img.shields.io/pypi/v/polyfactory?labelColor=202235&color=edb641&logo=python&logoColor=edb641)](https://badge.fury.io/py/polyfactory) ![PyPI - Support Python Versions](https://img.shields.io/pypi/pyversions/polyfactory?labelColor=202235&color=edb641&logo=python&logoColor=edb641) ![Pydantic Factories PyPI - Downloads](https://img.shields.io/pypi/dm/pydantic-factories?logo=python&label=Pydantic%20Factories%20downloads&labelColor=202235&color=edb641&logoColor=edb641) ![Polyfactory PyPI - Downloads](https://img.shields.io/pypi/dm/polyfactory?logo=python&label=Polyfactory%20downloads&labelColor=202235&color=edb641&logoColor=edb641) | | Community | | [![Reddit](https://img.shields.io/reddit/subreddit-subscribers/litestarapi?label=r%2FLitestar&logo=reddit&labelColor=202235&color=edb641&logoColor=edb641)](https://reddit.com/r/litestarapi) [![Discord](https://img.shields.io/discord/919193495116337154?labelColor=202235&color=edb641&label=chat%20on%20discord&logo=discord&logoColor=edb641)](https://discord.gg/X3FJqy8d2j) [![Matrix](https://img.shields.io/badge/chat%20on%20Matrix-bridged-202235?labelColor=202235&color=edb641&logo=matrix&logoColor=edb641)](https://matrix.to/#/#litestar:matrix.org) [![Medium](https://img.shields.io/badge/Medium-202235?labelColor=202235&color=edb641&logo=medium&logoColor=edb641)](https://blog.litestar.dev) [![Twitter](https://img.shields.io/twitter/follow/LitestarAPI?labelColor=202235&color=edb641&logo=twitter&logoColor=edb641&style=flat)](https://twitter.com/LitestarAPI) [![Blog](https://img.shields.io/badge/Blog-litestar.dev-202235?logo=blogger&labelColor=202235&color=edb641&logoColor=edb641)](https://blog.litestar.dev) | diff --git a/docs/conf.py b/docs/conf.py index bb1f1db5..a41e9c0a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -114,7 +114,7 @@ # -- Style configuration ----------------------------------------------------- html_theme = "litestar_sphinx_theme" -html_title = "Litestar Framework" +html_title = "Polyfactory" # pygments_style = "lightbulb" todo_include_todos = True diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 00000000..ad796521 --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,42 @@ +=============== +Getting Started +=============== + +Polyfactory is a simple and powerful mock data generation library, based around type +hints and supporting :doc:`dataclasses `, :class:`TypedDicts `, +Pydantic models, :class:`msgspec Struct's ` and more. + +Installation +------------ + +.. code-block:: bash + + pip install polyfactory + +Example +------- + +.. literalinclude:: /examples/declaring_factories/test_example_1.py + :caption: Minimal example using a dataclass + :language: python + +That is it - with almost no work, we are able to create a mock data object fitting the ``Person`` class model definition. + +This is possible because of the typing information available on the dataclass, which are used as a +source of truth for data generation. + +The factory parses the information stored in the dataclass and generates a dictionary of kwargs that are passed to +the ``Person`` class constructor. + +Relation to ``pydantic-factories`` +---------------------------------- + +Prior to version 2, this library was known as `pydantic-factories `_, a +name under which it gained quite a bit of popularity. + +A main motivator for the 2.0 release was that we wanted to support more than just Pydantic models, something which also +required a change to its core architecture. As this library would no longer be directly tied to Pydantic, ``polyfactory`` +was chosen as its new name to reflect its capabilities; It can generate mock data for +:doc:`dataclasses `, :class:`TypedDicts `, +`Pydantic `_, `Odmantic `_, +and `Beanie ODM `_ models, as well as custom factories. diff --git a/docs/index.rst b/docs/index.rst index d0860411..12912e8a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,56 +1,153 @@ -Polyfactory -=========== +:layout: landing +:description: Polyfactory is a simple and powerful mock data generation library. -Polyfactory is a simple and powerful mock data generation library, based around type -hints and supporting :doc:`dataclasses `, :class:`TypedDicts `, -Pydantic models, :class:`msgspec Struct's ` and more. +.. container:: + :name: home-head -Installation ------------- + .. container:: -.. code-block:: bash + .. image:: https://raw.githubusercontent.com/litestar-org/branding/main/assets/Branding%20-%20SVG%20-%20Transparent/Polyfactory%20-%20Banner%20-%20Inline%20-%20Light.svg + :alt: Litestar - Polyfactory + :width: 100% + :height: 400 - pip install polyfactory + .. container:: badges + :name: badges -Example -------- + .. image:: https://img.shields.io/github/actions/workflow/status/litestar-org/polyfactory/publish.yml?labelColor=202235&logo=github&logoColor=edb641 + :alt: GitHub Actions Latest Release Workflow Status -.. literalinclude:: /examples/declaring_factories/test_example_1.py - :caption: Minimal example using a dataclass - :language: python + .. image:: https://img.shields.io/github/actions/workflow/status/litestar-org/polyfactory/ci.yml?labelColor=202235&logo=github&logoColor=edb641 + :alt: GitHub Actions CI Workflow Status -That is it - with almost no work, we are able to create a mock data object fitting the ``Person`` class model definition. + .. image:: https://img.shields.io/github/actions/workflow/status/litestar-org/polyfactory/docs.yml?labelColor=202235&logo=github&logoColor=edb641 + :alt: GitHub Actions Docs Build Workflow Status -This is possible because of the typing information available on the dataclass, which are used as a -source of truth for data generation. + .. image:: https://img.shields.io/codecov/c/github/litestar-org/polyfactory?labelColor=202235&logo=codecov&logoColor=edb641 + :alt: Coverage -The factory parses the information stored in the dataclass and generates a dictionary of kwargs that are passed to -the ``Person`` class constructor. + .. image:: https://img.shields.io/pypi/v/litestar?labelColor=202235&color=edb641&logo=python&logoColor=edb641 + :alt: PyPI Version -Relation to ``pydantic-factories`` ----------------------------------- + .. image:: https://img.shields.io/github/all-contributors/litestar-org/polyfactory?labelColor=202235&color=edb641&logoColor=edb641 + :alt: Contributor Count -Prior to version 2, this library was known as `pydantic-factories `_, a -name under which it gained quite a bit of popularity. + .. image:: https://img.shields.io/pypi/dm/litestar?logo=python&label=litestar%20downloads&labelColor=202235&color=edb641&logoColor=edb641 + :alt: PyPI Downloads -A main motivator for the 2.0 release was that we wanted to support more than just Pydantic models, something which also -required a change to its core architecture. As this library would no longer be directly tied to Pydantic, ``polyfactory`` -was chosen as its new name to reflect its capabilities; It can generate mock data for -:doc:`dataclasses `, :class:`TypedDicts `, -`Pydantic `_, `Odmantic `_, -and `Beanie ODM `_ models, as well as custom factories. + .. image:: https://img.shields.io/pypi/pyversions/litestar?labelColor=202235&color=edb641&logo=python&logoColor=edb641 + :alt: Supported Python Versions + +.. rst-class:: lead + + Polyfactory is a simple and powerful mock data generation library, based around type + hints and supporting :doc:`dataclasses `, :class:`TypedDicts `, + Pydantic models, :class:`msgspec Struct's ` and more. + +.. container:: buttons + + :doc:`Get Started ` + `Usage Docs `_ + `API Docs `_ + `Blog `_ + +.. grid:: 1 1 2 2 + :padding: 0 + :gutter: 2 + + .. grid-item-card:: :octicon:`versions` Changelog + :link: changelog + :link-type: doc + + The latest updates and enhancements to Polyfactory + + .. grid-item-card:: :octicon:`comment-discussion` Discussions + :link: https://github.com/litestar-org/polyfactory/discussions + + Join discussions, pose questions, or share insights. + + .. grid-item-card:: :octicon:`issue-opened` Issues + :link: https://github.com/litestar-org/polyfactory/issues + + Report issues or suggest new features. + + .. grid-item-card:: :octicon:`beaker` Contributing + :link: contribution-guide + :link-type: doc + + Contribute to Litestar's growth with code, docs, and more. + +Sponsors +-------- + +.. rst-class:: lead + + Litestar is a community-driven, open-source initiative that thrives on the generous contributions of our sponsors, + enabling us to pursue innovative developments and continue our mission to provide exceptional tools and resources + to our users. + + +A huge thank you to our current sponsors: + +.. container:: + :name: sponsors-section + + .. grid:: 3 + :class-row: surface + :padding: 0 + :gutter: 2 + + .. grid-item-card:: + :link: https://github.com/scalar/scalar + + .. image:: https://raw.githubusercontent.com/litestar-org/branding/main/assets/sponsors/scalar.svg + :alt: Scalar.com + :class: sponsor + + `Scalar.com `_ + + .. grid-item-card:: + :link: https://telemetrysports.com/ + + .. image:: https://raw.githubusercontent.com/litestar-org/branding/main/assets/sponsors/telemetry-sports/unofficial-telemetry-whitebg.svg + :alt: Telemetry Sports + :class: sponsor + + `Telemetry Sports `_ + + .. grid-item-card:: + :link: https://www.stok.kr/ + + .. image:: https://avatars.githubusercontent.com/u/144093421 + :alt: Stok + :class: sponsor + + `Stok `_ + +We invite organizations and individuals to join our sponsorship program. +By becoming a sponsor on platforms like `Polar `_, `GitHub `_ +and `Open Collective `_, you can play a pivotal role in our project's growth. + +On top of regular sponsorship, we engage in pledge-based sponsorship opportunities through `Polar `_, +where you can pledge an amount towards an issue or feature you would like to see implemented. + + +.. _sponsor-github: https://github.com/sponsors/litestar-org +.. _sponsor-oc: https://opencollective.com/litestar +.. _sponsor-polar: https://polar.sh/litestar-org .. toctree:: :titlesonly: :caption: Documentation :hidden: + getting-started usage/index reference/index .. toctree:: :titlesonly: - :caption: Development + :caption: Contributing :hidden: changelog