From 272ca4d5becf0063afe5fa3eb1f1d2101e9ed85b Mon Sep 17 00:00:00 2001 From: masklinn Date: Sun, 2 Jul 2023 21:28:16 +0200 Subject: [PATCH] Documentation for the new API --- .gitignore | 2 ++ changelog.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile | 20 ++++++++++++++++++ doc/api.rst | 27 +++++++++++++++++++++++++ doc/changelog.rst | 1 + doc/conf.py | 35 ++++++++++++++++++++++++++++++++ doc/development.rst | 44 ++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 24 ++++++++++++++++++++++ doc/make.bat | 35 ++++++++++++++++++++++++++++++++ doc/migrating.rst | 22 ++++++++++++++++++++ doc/quickstart.rst | 1 + tox.ini | 7 +++++++ 12 files changed, 267 insertions(+) create mode 100644 changelog.rst create mode 100644 doc/Makefile create mode 100644 doc/api.rst create mode 120000 doc/changelog.rst create mode 100644 doc/conf.py create mode 100644 doc/development.rst create mode 100644 doc/index.rst create mode 100644 doc/make.bat create mode 100644 doc/migrating.rst create mode 120000 doc/quickstart.rst diff --git a/.gitignore b/.gitignore index 1f955509..c3a6ce69 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,5 @@ dist/ tmp/ regexes.yaml _regexes.py +# sphinx build dir +_build/ diff --git a/changelog.rst b/changelog.rst new file mode 100644 index 00000000..09c79330 --- /dev/null +++ b/changelog.rst @@ -0,0 +1,49 @@ +Changelog +--------- + +This repository is mostly a wrapper for the `User Agent String Parser +`_ data. + +As such, "data" changes should be lookled up in `the main project's +releases `_, at least +assuming this is synchronised. + +API-level changes are documented below: + +1.0 (pending) +~~~~~~~~~~~~~ + +First truly major change in a long time. I still have no idea what +versioning scheme to use though. + +- Dropped compatibility with CPython 2.7, CPython 3.6, and CPython + 3.7, this includes the legacy API. +- A brand new fully typed API following PEP8 conventions has been + added, the surface follows the logic of the old one (because it's + simple and it works) but it returns proper instances (rather than + undifferentiated dicts) and should allow for the development of + faster opt-in parsers with less fear of breaking existing use-cases. + + Notably, the new API also makes initialising parsers from custom + yaml files rather more practical than having to set an environment + variable. + + Consider migrating. +- The new API switches over from the google-style to the sphinx-style + docstring format as hopefully we'll publish something on RTD + eventually. +- The legacy parsing API (``ua_parser.user_agent_parser``) is + recommended against but not deprecated yet, although the ``Parse*`` + functions are pending deprecation, and: + + - ``PrettyUserAgent`` and ``PrettyOS`` are tentatively deprecated as + it's not clear what their use-case is, but they could be + un-deprecated. + - Any use of the ``jsParseBits`` (js overrides in the ``Parse*`` + functions) is deprecated. + - ``GetFilters`` is deprecated. + - ``ParseWithJSOverrides`` and ``Pretty`` are formally deprecated + (they were never not deprecated). + - The ``MatchSpans`` methods of the ``*Parser`` objects has been + removed, they're undocumented, not used internally, and don't have + a clear purpose. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/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) diff --git a/doc/api.rst b/doc/api.rst new file mode 100644 index 00000000..81bedfe3 --- /dev/null +++ b/doc/api.rst @@ -0,0 +1,27 @@ +API +=== + +Main Helpers +------------ + +.. automodule:: ua_parser + :members: + +Core Types +---------- + +.. automodule:: ua_parser.types + :members: + +Basic Parser +------------ + +.. automodule:: ua_parser.basic + :members: + +Caches +------ + +.. automodule:: ua_parser.caching + :members: + diff --git a/doc/changelog.rst b/doc/changelog.rst new file mode 120000 index 00000000..9dec46f3 --- /dev/null +++ b/doc/changelog.rst @@ -0,0 +1 @@ +../changelog.rst \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..8705a7d6 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,35 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "ua-parser" +copyright = "2023, ua-parser team" +author = "ua-parser team" + +version = "1.0.0a2" +release = "1.0.0a2" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.intersphinx"] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "alabaster" +html_static_path = ["_static"] + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} + +autodoc_member_order = "bysource" +autodoc_default_flags = ["members", "special-members"] diff --git a/doc/development.rst b/doc/development.rst new file mode 100644 index 00000000..59bce4e6 --- /dev/null +++ b/doc/development.rst @@ -0,0 +1,44 @@ +.. highlight:: sh + +Development +=========== + +Prerequisites +------------- + +- git +- tox_, not entirely required but probably a good idea in order to run + tests and maintenance tasks locally +- optionally something like pyenv_ in order to install multiple + version of Python and run tests with all of them, see + :download:`../tox.ini` for the currently supported list + +Setup +----- + +Clone the project from github:: + + $ git clone --recurse-submodule https://github.com/ua-parser/uap-python + +The project mostly uses tox_ to run tests and maintenance task, `tox +exec`_ can be used to open shells in the environments for interactive +testing. + +However it's also possible to install from the local copy, either via +an editable install:: + + $ pip install -e . + +which allows editing the code and having it reflect immediately in the +installation (code generation excluded), or a regular install:: + + $ pip install . + +which requires re-installing after each change. + +Tox +--- + +.. _pyenv: https://github.com/pyenv/pyenv +.. _tox: https://tox.wiki/en/latest/index.html +.. _tox exec: https://tox.wiki/en/latest/cli_interface.html#tox-exec-(e) diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..dc6a87f2 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,24 @@ +.. ua-parser documentation master file, created by + sphinx-quickstart on Sun Jul 2 21:43:06 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to ua-parser's documentation! +===================================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + quickstart + api + migrating + changelog + development + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/migrating.rst b/doc/migrating.rst new file mode 100644 index 00000000..5e41a083 --- /dev/null +++ b/doc/migrating.rst @@ -0,0 +1,22 @@ +Migrating from 0.x +================== + +While migrating is not quite necessary as the legacy API is not +getting removed just yet, it's also pretty simple: + +- Remove one level of API, while the utility functions of the legacy + API live in ``ua_parser.user_agent_parser`` the new API lives in + ``ua_parser`` at the root of the package. +- Convert the function names from ``PascalCase`` to ``snake_case``. +- Wrap the calls in ``dataclasses.asdict``: the functions now return + proper types, but these types are directly compatible with the old + results. + + Alternatively, convert the caller code to leveraging the new typed + API, items become attributes, and optional attributes are `Optional + `_. + +That should be it. If there are issues with the process, `just ask +`_ +or `open an issue +`_. diff --git a/doc/quickstart.rst b/doc/quickstart.rst new file mode 120000 index 00000000..89a01069 --- /dev/null +++ b/doc/quickstart.rst @@ -0,0 +1 @@ +../README.rst \ No newline at end of file diff --git a/tox.ini b/tox.ini index 5e6cc01e..094cf67f 100644 --- a/tox.ini +++ b/tox.ini @@ -45,6 +45,13 @@ deps = types-PyYaml commands = mypy --check-untyped-defs --no-implicit-optional {posargs:src tests} +[testenv:doc] +deps = + sphinx + pyyaml +allowlist_externals = make, sphinx-build +commands = make -C doc {posargs} + [flake8] max_line_length = 88 filename = src/ua_parser/