doc: contribution page and readme improvements

README.md

@@ -1,3 +1,47 @@
-# pydantic-scim2 [![Documentation Status](https://readthedocs.org/projects/pydantic-scim2/badge/?version=latest)](https://pydantic-scim2.readthedocs.io/en/latest/?badge=latest) ![Unit tests](https://github.com/yaal-coop/pydantic-scim2/actions/workflows/tests.yaml/badge.svg)
+# pydantic-scim2
 
-Fork of [pydantic-scim](https://github.com/chalk-ai/pydantic-scim) to bring support for pydantic 2.
+Pydantic models for SCIM2 schemas defined in [RFC7643](https://www.rfc-editor.org/rfc/rfc7643).
+This allows to parse and produce SCIM2 payloads.
+
+pydantic-scim2 is a fork of [pydantic-scim](https://github.com/chalk-ai/pydantic-scim) to bring support for pydantic 2.
+
+## Installation
+
+```shell
+pip install pydantic-scim2
+```
+
+## Example
+
+```python
+from pydantic_scim2 import User
+import datetime
+
+payload = {
+    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+    "id": "2819c223-7f76-453a-919d-413861904646",
+    "userName": "[email protected]",
+    "meta": {
+        "resourceType": "User",
+        "created": "2010-01-23T04:56:22Z",
+        "lastModified": "2011-05-13T04:42:34Z",
+        "version": 'W\\/"3694e05e9dff590"',
+        "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
+    },
+}
+
+# Pythonize JSON SCIM payload:
+
+user = User.model_validate(payload)
+assert user.userName == "[email protected]"
+assert user.meta.created == datetime.datetime(
+    2010, 1, 23, 4, 56, 22, tzinfo=datetime.timezone.utc
+)
+
+# JSONify Python SCIM models:
+
+dump = user.model_dump(
+    exclude_none=True, exclude_unset=True, by_alias=True, mode="json",
+)
+assert dump == payload
+```

doc/conf.py

@@ -10,13 +10,13 @@
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosectionlabel",
     "sphinx.ext.doctest",
     "sphinx.ext.graphviz",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinxcontrib.autodoc_pydantic",
+    "myst_parser",
 ]
 
 templates_path = ["_templates"]
@@ -25,6 +25,11 @@
 year = datetime.datetime.now().strftime("%Y")
 copyright = f"{year}, Yaal Coop"
 author = "Yaal Coop"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "markdown",
+    ".md": "markdown",
+}
 
 version = metadata.version("pydantic-scim2")
 language = "en"
@@ -51,6 +56,20 @@
         {
             "title": "SCIM",
             "url": "https://simplecloud.info/",
+            "children": [
+                {
+                    "title": "RFC7642 - SCIM: Definitions, Overview, Concepts, and Requirements",
+                    "url": "https://tools.ietf.org/html/rfc7642",
+                },
+                {
+                    "title": "RFC7644 - SCIM: Protocol",
+                    "url": "https://tools.ietf.org/html/rfc7643",
+                },
+                {
+                    "title": "RFC7643 - SCIM: Core Schema",
+                    "url": "https://tools.ietf.org/html/rfc7644",
+                },
+            ],
         },
         {"title": "PyPI", "url": "https://pypi.org/project/pydantic-scim2"},
     ],
@@ -62,8 +81,3 @@
     "source_version": "main",
     "source_docs_path": "/doc/",
 }
-
-# -- Options for autosectionlabel -----------------------------------------
-
-autosectionlabel_prefix_document = True
-autosectionlabel_maxdepth = 2

doc/contributing.rst

@@ -0,0 +1,47 @@
+Contributions
+=============
+
+Contributions are welcome!
+
+The repository is hosted at `github.com/yaal-coop/pydantic-scim2 <https://github.com/yaal-coop/pydantic-scim2>`_.
+
+Discuss
+-------
+
+If you want to implement a feature or a bugfix, please start by discussing it with us on
+the `bugtracker <https://github.com/yaal-coop/pydantic-scim2/issues>`_.
+
+Unit tests
+----------
+
+To run the tests, you just can run `poetry run pytest` and/or `tox` to test all the supported python environments.
+Everything must be green before patches get merged.
+
+The test coverage is 100%, patches won't be accepted if not entirely covered. You can check the
+test coverage with ``poetry run pytest --cov --cov-report=html`` or ``tox -e coverage -- --cov-report=html``.
+You can check the HTML coverage report in the newly created `htmlcov` directory.
+
+Code style
+----------
+
+We use `ruff <https://docs.astral.sh/ruff/>`_ along with other tools to format our code.
+Please run ``tox -e style`` on your patches before submiting them.
+In order to perform a style check and correction at each commit you can use our
+`pre-commit <https://pre-commit.com/>`_ configuration with ``pre-commit install``.
+
+Documentation
+-------------
+
+The documentation is generated when the tests run:
+
+.. code-block:: bash
+
+    tox -e doc
+
+You can also run sphinx by hand, that should be faster since it avoids the tox environment initialization:
+
+.. code-block:: bash
+
+   sphinx-build doc build/sphinx/html
+
+The generated documentation is located at ``build/sphinx/html``.

doc/index.rst

@@ -1,10 +1,12 @@
-pydantic-scim2
-==============
+.. include:: ../README.md
+   :parser: myst_parser.parsers.docutils_
 
-SCIM2 models for pydantic
+Table of contents
+-----------------
 
 .. toctree::
     :maxdepth: 2
 
     reference
+    contributing
     changelog

pyproject.toml

@@ -39,6 +39,7 @@ optional = true
 autodoc-pydantic = "^2.2.0"
 shibuya = "^2024.5.15"
 sphinx = "^7.3.7"
+myst-parser = "^3.0.1"
 
 [tool.coverage.run]
 source = [