From 1352676419129789278c61f5b8e2ea92dca5d19a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tin=20Tvrtkovi=C4=87?= Date: Tue, 14 Nov 2023 19:51:12 +0100 Subject: [PATCH] Doc improvements (#442) * Doc improvements * Add history link --- HISTORY.md | 1 + docs/Makefile | 11 ++++++++++ docs/converters.md | 3 +++ docs/usage.md | 8 +++---- pdm.lock | 54 ++++++++++++++++++++++++++++++++++++++++++---- pyproject.toml | 1 + 6 files changed, 69 insertions(+), 9 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index 27e4c773..4f39e691 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -54,6 +54,7 @@ ([#416](https://github.com/python-attrs/cattrs/pull/416)) - Fix handling classes inheriting from non-generic protocols. ([#374](https://github.com/python-attrs/cattrs/issues/374) [#436](https://github.com/python-attrs/cattrs/pull/436)) +- The documentation Makefile now supports the `htmlview` and `htmllive` targets. ([#442](https://github.com/python-attrs/cattrs/pull/442)) - _cattrs_ is now published using PyPI Trusted Publishers, and `main` branch commits are automatically deployed to Test PyPI. ## 23.1.2 (2023-06-02) diff --git a/docs/Makefile b/docs/Makefile index e8c0e5e6..c13822c9 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -173,3 +173,14 @@ pseudoxml: apidoc: pdm run sphinx-apidoc -o . ../src/cattrs/ -f + +## htmlview to open the index page built by the html target in your browser +.PHONY: htmlview +htmlview: html + pdm run python -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('$(BUILDDIR)/html/index.html'))" + +## htmllive to rebuild and reload HTML files in your browser +.PHONY: htmllive +htmllive: SPHINXBUILD = pdm run sphinx-autobuild +htmllive: SPHINXERRORHANDLING = --re-ignore="/\.idea/|/venv/|/pep-0000.rst|/topic/" +htmllive: html diff --git a/docs/converters.md b/docs/converters.md index 05c04bf7..db17c520 100644 --- a/docs/converters.md +++ b/docs/converters.md @@ -21,6 +21,9 @@ Larger applications are strongly encouraged to create and customize a different, ## Converter Objects To create a private converter, simply instantiate a {class}`cattrs.Converter`. + +The core functionality of a converter is [structuring](structuring.md) and [unstructuring](unstructuring.md) data by composing provided and [custom handling functions](customizing.md), called _hooks_. + Currently, a converter contains the following state: - a registry of unstructure hooks, backed by a [singledispatch](https://docs.python.org/3/library/functools.html#functools.singledispatch) and a `function_dispatch`. diff --git a/docs/usage.md b/docs/usage.md index 9e6cf9a6..f0536201 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -4,12 +4,10 @@ This section covers common use examples of _cattrs_ features. ## Using Pendulum for Dates and Time -To use the excellent [Pendulum](https://pendulum.eustace.io/) library for datetimes, we need to register -structuring and unstructuring hooks for it. +To use the [Pendulum](https://pendulum.eustace.io/) library for datetimes, we need to register structuring and unstructuring hooks for it. -First, we need to decide on the unstructured representation of a datetime -instance. Since all our datetimes will use the UTC time zone, we decide to -use the UNIX epoch timestamp as our unstructured representation. +First, we need to decide on the unstructured representation of a datetime instance. +Since all our datetimes will use the UTC time zone, we decide to use the UNIX epoch timestamp as our unstructured representation. Define a class using Pendulum's `DateTime`: diff --git a/pdm.lock b/pdm.lock index 2ed3330f..d2592552 100644 --- a/pdm.lock +++ b/pdm.lock @@ -3,10 +3,9 @@ [metadata] groups = ["default", "bench", "bson", "cbor2", "docs", "lint", "msgpack", "orjson", "pyyaml", "test", "tomlkit", "ujson"] -cross_platform = true -static_urls = false -lock_version = "4.3" -content_hash = "sha256:ed3b6e1fa2a5a5d7d9d7cdef0860186597028f7b9db1ffc788ab430e0b1de086" +strategy = ["cross_platform"] +lock_version = "4.4" +content_hash = "sha256:152c4f9bcb326e99412fec0cece87b2a3c7da06a0b49f38e6dfe83fd0821cb1c" [[package]] name = "alabaster" @@ -470,6 +469,19 @@ files = [ {file = "Jinja2-3.1.2.tar.gz", hash = "sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852"}, ] +[[package]] +name = "livereload" +version = "2.6.3" +summary = "Python LiveReload is an awesome tool for web developers" +dependencies = [ + "six", + "tornado; python_version > \"2.7\"", +] +files = [ + {file = "livereload-2.6.3-py2.py3-none-any.whl", hash = "sha256:ad4ac6f53b2d62bb6ce1a5e6e96f1f00976a32348afedcb4b6d68df2a1d346e4"}, + {file = "livereload-2.6.3.tar.gz", hash = "sha256:776f2f865e59fde56490a56bcc6773b6917366bce0c267c60ee8aaf1a0959869"}, +] + [[package]] name = "markdown-it-py" version = "3.0.0" @@ -1093,6 +1105,21 @@ files = [ {file = "sphinx-7.1.2.tar.gz", hash = "sha256:780f4d32f1d7d1126576e0e5ecc19dc32ab76cd24e950228dcf7b1f6d3d9e22f"}, ] +[[package]] +name = "sphinx-autobuild" +version = "2021.3.14" +requires_python = ">=3.6" +summary = "Rebuild Sphinx documentation on changes, with live-reload in the browser." +dependencies = [ + "colorama", + "livereload", + "sphinx", +] +files = [ + {file = "sphinx-autobuild-2021.3.14.tar.gz", hash = "sha256:de1ca3b66e271d2b5b5140c35034c89e47f263f2cd5db302c9217065f7443f05"}, + {file = "sphinx_autobuild-2021.3.14-py3-none-any.whl", hash = "sha256:8fe8cbfdb75db04475232f05187c776f46f6e9e04cacf1e49ce81bdac649ccac"}, +] + [[package]] name = "sphinx-basic-ng" version = "1.0.0b2" @@ -1199,6 +1226,25 @@ files = [ {file = "tomlkit-0.12.1.tar.gz", hash = "sha256:38e1ff8edb991273ec9f6181244a6a391ac30e9f5098e7535640ea6be97a7c86"}, ] +[[package]] +name = "tornado" +version = "6.3.3" +requires_python = ">= 3.8" +summary = "Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed." +files = [ + {file = "tornado-6.3.3-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:502fba735c84450974fec147340016ad928d29f1e91f49be168c0a4c18181e1d"}, + {file = "tornado-6.3.3-cp38-abi3-macosx_10_9_x86_64.whl", hash = "sha256:805d507b1f588320c26f7f097108eb4023bbaa984d63176d1652e184ba24270a"}, + {file = "tornado-6.3.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1bd19ca6c16882e4d37368e0152f99c099bad93e0950ce55e71daed74045908f"}, + {file = "tornado-6.3.3-cp38-abi3-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7ac51f42808cca9b3613f51ffe2a965c8525cb1b00b7b2d56828b8045354f76a"}, + {file = "tornado-6.3.3-cp38-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:71a8db65160a3c55d61839b7302a9a400074c9c753040455494e2af74e2501f2"}, + {file = "tornado-6.3.3-cp38-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:ceb917a50cd35882b57600709dd5421a418c29ddc852da8bcdab1f0db33406b0"}, + {file = "tornado-6.3.3-cp38-abi3-musllinux_1_1_i686.whl", hash = "sha256:7d01abc57ea0dbb51ddfed477dfe22719d376119844e33c661d873bf9c0e4a16"}, + {file = "tornado-6.3.3-cp38-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:9dc4444c0defcd3929d5c1eb5706cbe1b116e762ff3e0deca8b715d14bf6ec17"}, + {file = "tornado-6.3.3-cp38-abi3-win32.whl", hash = "sha256:65ceca9500383fbdf33a98c0087cb975b2ef3bfb874cb35b8de8740cf7f41bd3"}, + {file = "tornado-6.3.3-cp38-abi3-win_amd64.whl", hash = "sha256:22d3c2fa10b5793da13c807e6fc38ff49a4f6e1e3868b0a6f4164768bb8e20f5"}, + {file = "tornado-6.3.3.tar.gz", hash = "sha256:e7d8db41c0181c80d76c982aacc442c0783a2c54d6400fe028954201a2e032fe"}, +] + [[package]] name = "typing-extensions" version = "4.7.1" diff --git a/pyproject.toml b/pyproject.toml index af1d897f..2cb0b30f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -29,6 +29,7 @@ docs = [ "sphinx-copybutton>=0.5.2", "myst-parser>=1.0.0", "pendulum>=2.1.2", + "sphinx-autobuild", ] bench = [ "pyperf>=2.6.1",