Skip to content

Commit

Permalink
Doc improvements (#442)
Browse files Browse the repository at this point in the history
* Doc improvements

* Add history link
  • Loading branch information
Tinche authored Nov 14, 2023
1 parent 53a5c9d commit 1352676
Showing 6 changed files with 69 additions and 9 deletions.
1 change: 1 addition & 0 deletions HISTORY.md
Original file line number Diff line number Diff line change
@@ -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)
11 changes: 11 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions docs/converters.md
Original file line number Diff line number Diff line change
@@ -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`.
8 changes: 3 additions & 5 deletions docs/usage.md
Original file line number Diff line number Diff line change
@@ -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`:

54 changes: 50 additions & 4 deletions pdm.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -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",

0 comments on commit 1352676

Please sign in to comment.