Merge branch 'master' into independent-checkers

.gitignore

@@ -8,3 +8,4 @@ dist/
 tmp/
 regexes.yaml
 _regexes.py
+doc/_build

README.rst

@@ -30,8 +30,20 @@ Just add ``ua-parser`` to your project's dependencies, or run
 
 to install in the current environment.
 
-Getting Started
----------------
+Installing `google-re2 <https://pypi.org/project/google-re2/>`_ is
+*strongly* recommended as it leads to *significantly* better
+performances. This can be done directly via the ``re2`` optional
+dependency:
+
+.. code-block:: sh
+
+    $ pip install 'ua_parser[re2]'
+
+If ``re2`` is available, ``ua-parser`` will simply use it by default
+instead of the pure-python resolver.
+
+Quick Start
+-----------
 
 Retrieve all data on a user-agent string
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -41,25 +53,25 @@ Retrieve all data on a user-agent string
     >>> from ua_parser import parse
     >>> ua_string = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.104 Safari/537.36'
     >>> parse(ua_string) # doctest: +NORMALIZE_WHITESPACE, +ELLIPSIS
-    ParseResult(user_agent=UserAgent(family='Chrome',
-                                     major='41',
-                                     minor='0',
-                                     patch='2272',
-                                     patch_minor='104'),
-                os=OS(family='Mac OS X',
-                      major='10',
-                      minor='9',
-                      patch='4',
-                      patch_minor=None),
-                device=Device(family='Mac',
-                              brand='Apple',
-                              model='Mac'),
-                string='Mozilla/5.0 (Macintosh; Intel Mac OS...
+    Result(user_agent=UserAgent(family='Chrome',
+                                major='41',
+                                minor='0',
+                                patch='2272',
+                                patch_minor='104'),
+           os=OS(family='Mac OS X',
+                 major='10',
+                 minor='9',
+                 patch='4',
+                 patch_minor=None),
+           device=Device(family='Mac',
+                         brand='Apple',
+                         model='Mac'),
+           string='Mozilla/5.0 (Macintosh; Intel Mac OS...
 
 Any datum not found in the user agent string is set to ``None``::
 
     >>> parse("")
-    ParseResult(user_agent=None, os=None, device=None, string='')
+    Result(user_agent=None, os=None, device=None, string='')
 
 Extract only browser data from user-agent string
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,43 +106,3 @@ Extract device information from user-agent string
     >>> ua_string = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.104 Safari/537.36'
     >>> parse_device(ua_string)
     Device(family='Mac', brand='Apple', model='Mac')
-
-Parser
-~~~~~~
-
-Parsers expose the same functions (``parse``, ``parse_user_agent``,
-``parse_os``, and ``parse_device``) as the top-level of the package,
-however these are all *utility* methods.
-
-The actual protocol of parsers, and the one method which must be
-implemented / overridden is::
-
-    def __call__(self, str, Components, /) -> ParseResult:
-
-It's similar to but more flexible than ``parse``:
-
-- The ``str`` is the user agent string.
-- The ``Components`` is a hint, through which the caller requests the
-  domain (component) they are looking for, any combination of
-  ``Components.USER_AGENT``, ``Components.OS``, and
-  ``Components.DEVICE``. ``Domains.ALL`` exists as a convenience alias
-  for the combination of all three.
-
-  The parser *must* return at least the requested information, but if
-  that's more convenient or no more expensive it *can* return more.
-- The ``ParseResult`` is similar to ``CompleteParseResult``, except
-  all the attributes are ``Optional`` and it has a ``components:
-  Components`` attribute which specifies whether a component was never
-  requested (its value for the user agent string is unknown) or it has
-  been requested but could not be resolved (no match was found for the
-  user agent).
-
-  ``ParseResult.complete()`` convert to a ``CompleteParseResult`` if
-  all the components are set, and raise an exception otherwise. If
-  some of the components are set to ``None``, they'll be swapped for a
-  default value.
-
-Calling the parser directly is part of the public API. One of the
-advantage is that it does not return default values, as such it allows
-more easily differentiating between a non-match (= ``None``) and a
-default fallback (``family = "Other"``).

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/_templates/navigation.html

@@ -0,0 +1,10 @@
+<h3>{{ _('Navigation') }}</h3>
+{{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse, maxdepth=3) }}
+{% if theme_extra_nav_links %}
+<hr />
+<ul>
+    {% for text, uri in theme_extra_nav_links.items() %}
+    <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li>
+    {% endfor %}
+</ul>
+{% endif %}