docs: Replace Sphinx index.rst with repo's README.md (#270)

docs: Improve `README.md` with update badges and remove animated gif comparison examples docs: Fix broken link in example section
mansenfranzen · Apr 24, 2024 · 40b5b22 · 40b5b22
1 parent 0be2710
commit 40b5b22
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 102 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,17 @@
 ![Autodoc Pydantic](https://raw.githubusercontent.com/mansenfranzen/autodoc_pydantic/main/docs/source/material/logo_black.svg)
 
-[![PyPI version](https://img.shields.io/pypi/v/autodoc_pydantic?style=for-the-badge)](https://pypi.org/project/autodoc-pydantic/)
-![Python](https://img.shields.io/badge/python-3.8+-blue.svg?style=for-the-badge)
-
-[![Master](https://img.shields.io/github/actions/workflow/status/mansenfranzen/autodoc_pydantic/tests.yml?branch=main&style=for-the-badge)](https://github.com/mansenfranzen/autodoc_pydantic/actions/workflows/tests.yml)
-[![Coverage](https://img.shields.io/codecov/c/gh/mansenfranzen/autodoc_pydantic?style=for-the-badge)](https://app.codecov.io/gh/mansenfranzen/autodoc_pydantic)
-
-[![Downloads](https://img.shields.io/pypi/dm/autodoc_pydantic?color=fe7d37&style=for-the-badge)](https://pypistats.org/packages/autodoc-pydantic)<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-49-orange.svg?style=for-the-badge)](#contributors)
+[![PyPI - Version](https://img.shields.io/pypi/v/autodoc_pydantic?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/autodoc_pydantic/)
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/autodoc_pydantic?style=for-the-badge&logo=python&logoColor=white&color=blue)](https://pypistats.org/packages/autodoc-pydantic)
+
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/mansenfranzen/autodoc_pydantic/tests-push-pr.yml?style=for-the-badge&logo=github)](https://github.com/mansenfranzen/autodoc_pydantic/actions)
+[![Codecov](https://img.shields.io/codecov/c/gh/mansenfranzen/autodoc_pydantic?style=for-the-badge&logo=codecov)](https://app.codecov.io/gh/mansenfranzen/autodoc_pydantic)
+[![Read the Docs (stable)](https://img.shields.io/readthedocs/autodoc_pydantic/stable?style=for-the-badge&logo=sphinx&label=Docs%20stable)](https://autodoc-pydantic.readthedocs.io/en/stable/)
+
+[![GitHub License](https://img.shields.io/github/license/mansenfranzen/autodoc_pydantic?style=for-the-badge&color=orange&logo=semanticscholar&logoColor=white)](https://github.com/mansenfranzen/autodoc_pydantic/blob/main/LICENSE)
+[![linting - ruff](https://img.shields.io/badge/Linting-orange?style=for-the-badge&logo=ruff&logoColor=white&label=ruff)](https://github.com/astral-sh/ruff)
+[![types - Mypy](https://img.shields.io/badge/types-Mypy-orange.svg?style=for-the-badge&logo=python&logoColor=white)](https://github.com/python/mypy)<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+[![All Contributors](https://img.shields.io/badge/all_contributors-49-orange.svg?style=for-the-badge&logo=iconify&logoColor=white)](https://github.com/mansenfranzen/autodoc_pydantic/tree/main?tab=readme-ov-file#acknowledgements)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 
@@ -19,7 +23,7 @@ does not integrate too well with pydantic models 😕.
 
 Don't worry - just `pip install autodoc_pydantic` ☺.
 
-## Features
+# 🌟 Features
 
 - 💬 provides default values, alias and constraints for model fields
 - 🔗 adds hyperlinks between validators and corresponding fields
@@ -32,24 +36,19 @@ Don't worry - just `pip install autodoc_pydantic` ☺.
 - 🔨 allows complete configurability on global and per-model level
 - 🍀 supports `pydantic >= 1.5.0` and `sphinx >= 4.0.0`
 
-## Documentation
-
-For more details, please visit the official [documentation](https://autodoc-pydantic.readthedocs.io/en/stable/):
-
-- [Installation](https://autodoc-pydantic.readthedocs.io/en/stable/users/installation.html)
-- [Configuration](https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html)
-- [Usage](https://autodoc-pydantic.readthedocs.io/en/stable/users/usage.html)
-- [Examples](https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html)
-- [Developer Guide](https://autodoc-pydantic.readthedocs.io/en/stable/developers/setup.html)
-
-## Comparison between autodoc sphinx and autodoc pydantic
+# 📄 Documentation
 
-[![Comparison](https://raw.githubusercontent.com/mansenfranzen/autodoc_pydantic/main/docs/source/material/example_comparison_v1.0.0.gif)](https://autodoc-pydantic.readthedocs.io/en/latest/examples.html#default-configuration)
+| Section                         | Description                           |
+|-----------------------------------------|-----------------------------------------|
+| [📑 Landing Page](https://autodoc-pydantic.readthedocs.io/en/stable/)    | Guides and detailed information.        |
+| [🛠️ Installation](https://autodoc-pydantic.readthedocs.io/en/stable/users/installation.html)      | Setup and installation procedures.      |
+| [🔧 Configuration](https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html)    | System or application settings.         |
+| [💡 Usage](https://autodoc-pydantic.readthedocs.io/en/stable/users/usage.html)                     | How to use the application or tool.     |
+| [🌐 Examples](https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html)              | Showcase and usage examples.                |
+| [👨‍💻 Developer Guide](https://autodoc-pydantic.readthedocs.io/en/stable/developers/setup.html) | In-depth guide for developers.          |
 
-To see those features in action, jump over to the [example documentation](https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html#default-configuration) to compare
-the appearance of standard sphinx autodoc with *autodoc_pydantic*.
 
-## Acknowledgements
+# 🙏 Acknowledgements
 
 Thanks to great open source projects [sphinx](https://www.sphinx-doc.org/en/master/),
 [pydantic](https://pydantic-docs.helpmanual.io/) and

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,43 +1,10 @@
-============================================
-Welcome to autodoc_pydantic's documentation!
-============================================
-
-**Seamlessly integrate pydantic models in your Sphinx documentation.**
-
-|PyPIBadge|_ |PythonBadge|_ |CIBadge|_ |CoverageBadge|_ |ContributersBadge|_ |DownloadsBadge|_
-
-You love `pydantic <https://pydantic-docs.helpmanual.io/>`_ 💖 and you want to
-document your models and configuration settings with `sphinx`_?
-Perfect, let's go. But wait, sphinx' `autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
-does not integrate too well with pydantic models 😕.
-Don't worry - just :code:`pip install autodoc_pydantic` 😉.
-
-Features
---------
-
-- 💬 provides default values, alias and constraints for model fields
-- 🔗 adds hyperlinks between validators and corresponding fields
-- 📃 includes collapsable model json schema
-- 🏄 natively integrates with autodoc and autosummary extensions
-- 📎 defines explicit pydantic prefixes for models, settings, fields, validators and model config
-- 📋 shows summary section for model configuration, fields and validators
-- 👀 hides overloaded and redundant model class signature
-- 🔱 visualizes entity-relationship-diagrams for class hierarchies
-- 🔨 allows complete configurability on global and per-model level
-- 🍀 supports `pydantic >= 1.5.0` and `sphinx >= 4.0.0`
-
-To see those features in action, jump over to the :ref:`example <showcase>` section comparing
-the appearance of standard sphinx autodoc with **autodoc_pydantic**.
-
-.. note::
-
-   This documentation is based on ``autodoc_pydantic >= 2.0.1``. If you are
-   using pydantic v1 along with ``autodoc_pydantic < 2.0.0``, please find the
-   latest v1 documentation `here <https://autodoc-pydantic.readthedocs.io/en/main-1.x/>`_ .
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 1
-   :caption: Users
+   :caption: 🙋 Users
+   :hidden:
 
    users/installation
    users/usage
@@ -47,7 +14,8 @@ the appearance of standard sphinx autodoc with **autodoc_pydantic**.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Developers
+   :caption: 🧑‍💻 Developers
+   :hidden:
 
    developers/setup
    developers/design
@@ -56,42 +24,8 @@ the appearance of standard sphinx autodoc with **autodoc_pydantic**.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Reference
+   :caption: 📖 Reference
+   :hidden:
 
    reference/api
-   reference/changelog
-
-
-Acknowledgements
-----------------
-
-Thanks to great open source projects
-
-- `sphinx`_
-- `pydantic <https://pydantic-docs.helpmanual.io/>`_
-- `poetry <https://python-poetry.org/>`_
-- `mermaid.js <https://mermaid-js.github.io/mermaid/#/>`_
-- and many more involved
-
-and all `contributors <https://github.com/mansenfranzen/autodoc_pydantic/tree/refactor_inspection#acknowledgements>`_ to **autodoc_pydantic** ❤!
-
-
-.. _sphinx: https://www.sphinx-doc.org/en/master
-
-.. |PyPIBadge| image:: https://img.shields.io/pypi/v/autodoc_pydantic?style=flat
-.. _PyPIBadge: https://pypi.org/project/autodoc-pydantic/
-
-.. |CIBadge| image:: https://img.shields.io/github/actions/workflow/status/mansenfranzen/autodoc_pydantic/tests.yml?branch=main&style=flat
-.. _CIBadge: https://github.com/mansenfranzen/autodoc_pydantic/actions/workflows/tests.yml
-
-.. |DownloadsBadge| image:: https://img.shields.io/pypi/dm/autodoc_pydantic?color=fe7d37&style=flat
-.. _DownloadsBadge: https://pypistats.org/packages/autodoc-pydantic
-
-.. |ContributersBadge| image:: https://img.shields.io/badge/all_contributors-47-orange.svg?style=flat
-.. _ContributersBadge: https://github.com/mansenfranzen/autodoc_pydantic/tree/refactor_inspection#acknowledgements
-
-.. |CoverageBadge| image:: https://img.shields.io/codecov/c/gh/mansenfranzen/autodoc_pydantic?style=flat
-.. _CoverageBadge: https://app.codecov.io/gh/mansenfranzen/autodoc_pydantic
-
-.. |PythonBadge| image:: https://img.shields.io/badge/python-3.8+-blue.svg?style=flat
-.. _PythonBadge: http://www.python.org/
+   reference/changelog
diff --git a/docs/source/material/example_comparison_v1.0.0.gif b/docs/source/material/example_comparison_v1.0.0.gif
diff --git a/docs/source/users/examples.rst b/docs/source/users/examples.rst
@@ -20,11 +20,11 @@ In contrast, it also shows how standard sphinx autodoc displays the same example
 
 .. tabs::
 
-   .. tab:: *rendered output pydantic*
+   .. tab:: *output autodoc_pydantic*
 
       .. autopydantic_settings:: target.example_setting.ExampleSettings
 
-   .. tab:: *rendered output sphinx*
+   .. tab:: *output default sphinx*
 
       .. autopydantic_settings:: target.example_setting.ExampleSettings
          :members:
@@ -118,7 +118,7 @@ concepts such as model validators, required/optional fields or generic models.
 Model validators
 ----------------
 
-This example highlights how ``model validators <https://docs.pydantic.dev/latest/usage/validators/#model-validators>`_
+This example highlights how `model validators <https://docs.pydantic.dev/latest/usage/validators/#model-validators>`_
 (``@model_validator`` or ``@field_validator('*')``) are represented. Since they
 validate all fields, their corresponding field reference is replaced with a
 simple ``all fields`` marker which hyperlinks to the related model itself.