Doc improvements (#442)

* Doc improvements

* Add history link

Author: Tinche

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)

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

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`.

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`:
 

pdm.lock

@@ -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",