From c0d17362122d1a871e46cf2a1f1f348972982a07 Mon Sep 17 00:00:00 2001 From: masklinn Date: Mon, 25 Nov 2024 17:23:30 +0100 Subject: [PATCH 1/4] Add configuration file for RTFD --- .readthedocs.yaml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..1eec072 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +# needed for uap-core to get initialised properly +submodules: + include: all + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + jobs: + post_checkout: + # rtfd doesn't retrieve tags by default, but we need them for `git + # describe` in order to build the parser builtins + # FIXME: remove once upb is published and can be installed from pypi) + - git fetch --unshallow --tags || true + +python: + install: + - method: pip + path: . + extra_requirements: + - yaml + - regex + - re2 + +sphinx: + configuration: doc/conf.py + fail_on_warning: true From f04c4cfd35ebc4678f9de54ec37a9cc98b6c3930 Mon Sep 17 00:00:00 2001 From: masklinn Date: Mon, 25 Nov 2024 17:56:31 +0100 Subject: [PATCH 2/4] Fix typo in directive (forgot space) which prevented the regex resolver from being documented --- doc/api.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 6f984a4..c77eee4 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -75,11 +75,12 @@ from user agent strings. .. warning:: Only available if |re2|_ is installed. -.. class::ua_parser.regex.Resolver(Matchers) +.. class:: ua_parser.regex.Resolver(Matchers) - An advanced resolver based on |regex|_ and a bespoke implementation - of regex prefiltering, by the sibling project `ua-rust - `_ and a bespoke implementation + of regex prefiltering, by the sibling project `uap-rust + `_. Sufficiently fast that a cache may not be necessary, and may even be detrimental at smaller cache sizes From 051110204a578326cf22bdf64f479abf60eb433b Mon Sep 17 00:00:00 2001 From: masklinn Date: Mon, 25 Nov 2024 18:46:39 +0100 Subject: [PATCH 3/4] Fix typos in the cache doc --- doc/advanced/caches.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/advanced/caches.rst b/doc/advanced/caches.rst index c804d7c..9f09701 100644 --- a/doc/advanced/caches.rst +++ b/doc/advanced/caches.rst @@ -45,14 +45,14 @@ exercises the caches themselves and barely looks at the data. ---------------------------- ``bench`` is much more expensive in both CPU and wallclock as it -actually runs the base resolvers, combined with various caches of -various sizes. For usability, it can report its data (the average -parse time per input entry) in both human-readable text with one -result per line and CSV with resolver configurations as the columns -and cache sizes as the rows. +actually runs the resolvers on the sample file, combined with various +caches of various sizes. For usability, it can report its data (the +average parse time per input entry) in both human-readable text with +one result per line and CSV with resolver configurations as the +columns and cache sizes as the rows. ``hitrates`` is generally sufficient as generally speaking for the -same base resolver performances tend to more or less follo hit rates: +same base resolver performances tend to more or less follow hit rates: a cache hit is close to free compared to a cache miss. Although this is truer for the basic resolver (for which misses tend to be very expensive). ``bench`` is mostly useful to validate or tie-break From 814b1f11bb3d1adbd8e3a462647b7f12834d5296 Mon Sep 17 00:00:00 2001 From: masklinn Date: Mon, 25 Nov 2024 19:31:09 +0100 Subject: [PATCH 4/4] Add doc badges, link action badge --- README.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.rst b/README.rst index 512d0d2..0cb76dd 100644 --- a/README.rst +++ b/README.rst @@ -8,8 +8,13 @@ Build Status ------------ .. image:: https://github.com/ua-parser/uap-python/actions/workflows/ci.yml/badge.svg + :target: https://github.com/ua-parser/uap-python/actions/workflows/ci.yml?query=branch%3Amaster :alt: CI on the master branch +.. image:: https://readthedocs.org/projects/uap-python/badge/?version=latest + :target: https://readthedocs.org/project/uap-python/en/latest/ + :alt: Documentation Status + Installing ----------