From d0ba48e6910ed6c516391dfd43bf7d4d72fd2bf4 Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Sun, 17 Dec 2023 12:03:51 -0500 Subject: [PATCH] Simple docs. --- .gitignore | 6 +++ .readthedocs.yml | 17 ++++++++ README.rst | 4 ++ docs/api.rst | 8 ++++ docs/conf.py | 87 +++++++++++++++++++++++++++++++++++++ docs/index.rst | 52 ++++++++++++++++++++++ docs/requirements.in | 9 ++++ docs/requirements.txt | 89 ++++++++++++++++++++++++++++++++++++++ docs/spelling-wordlist.txt | 0 9 files changed, 272 insertions(+) create mode 100644 .readthedocs.yml create mode 100644 docs/api.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.in create mode 100644 docs/requirements.txt create mode 100644 docs/spelling-wordlist.txt diff --git a/.gitignore b/.gitignore index c8f0442..62e01a9 100644 --- a/.gitignore +++ b/.gitignore @@ -70,3 +70,9 @@ docs/_build/ # Pyenv .python-version + +# User defined +/dirhtml +_cache + +TODO diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..e6ab173 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,17 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +sphinx: + builder: dirhtml + configuration: docs/conf.py + fail_on_warning: true + +formats: all + +python: + install: + - requirements: docs/requirements.txt diff --git a/README.rst b/README.rst index 13f0d9e..4f3e49b 100644 --- a/README.rst +++ b/README.rst @@ -16,6 +16,10 @@ :alt: Build status :target: https://github.com/crate-py/rpds/actions?query=workflow%3ACI +.. |ReadTheDocs| image:: https://readthedocs.org/projects/referencing/badge/?version=stable&style=flat + :alt: ReadTheDocs status + :target: https://referencing.readthedocs.io/en/stable/ + Python bindings to the `Rust rpds crate `_ for persistent data structures. diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..d978fca --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,8 @@ +API Reference +============= + +.. automodule:: rpds + :members: + :undoc-members: + :imported-members: + :special-members: __iter__, __getitem__, __len__, __rmatmul__ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..eb1c0bf --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,87 @@ +import importlib.metadata +import re + +from url import URL + +GITHUB = URL.parse("https://github.com/") +HOMEPAGE = GITHUB / "crate-py/rpds" + +project = "rpds.py" +author = "Julian Berman" +copyright = f"2023, {author}" + +release = importlib.metadata.version("rpds.py") +version = release.partition("-")[0] + +language = "en" +default_role = "any" + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx.ext.coverage", + "sphinx.ext.doctest", + "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", + "sphinx.ext.napoleon", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx_copybutton", + "sphinx_json_schema_spec", + "sphinxcontrib.spelling", + "sphinxext.opengraph", +] + +pygments_style = "lovelace" +pygments_dark_style = "one-dark" + +html_theme = "furo" + + +def entire_domain(host): + return r"http.?://" + re.escape(host) + r"($|/.*)" + + +linkcheck_ignore = [ + entire_domain("img.shields.io"), + f"{GITHUB}.*#.*", + str(HOMEPAGE / "actions"), + str(HOMEPAGE / "workflows/CI/badge.svg"), +] + +# = Extensions = + +# -- autodoc -- + +autodoc_default_options = { + "members": True, + "member-order": "bysource", +} + +# -- autosectionlabel -- + +autosectionlabel_prefix_document = True + +# -- intersphinx -- + +intersphinx_mapping = { + "python": ("https://docs.python.org/", None), +} + +# -- extlinks -- + +extlinks = { + "gh": (str(HOMEPAGE) + "/%s", None), + "github": (str(GITHUB) + "/%s", None), +} +extlinks_detect_hardcoded_links = True + +# -- sphinx-copybutton -- + +copybutton_prompt_text = r">>> |\.\.\. |\$" +copybutton_prompt_is_regexp = True + +# -- sphinxcontrib-spelling -- + +spelling_word_list_filename = "spelling-wordlist.txt" +spelling_show_suggestions = True diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..741eb17 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,52 @@ +Python bindings to the `Rust rpds crate `_ for persistent data structures. + +What's here is quite minimal (in transparency, it was written initially to support replacing ``pyrsistent`` in the `referencing library `_). +If you see something missing (which is very likely), a PR is definitely welcome to add it. + +Installation +------------ + +The distribution on PyPI is named ``rpds.py`` (equivalently ``rpds-py``), and thus can be installed via e.g.: + +.. code:: sh + + $ pip install rpds-py + +Note that if you install ``rpds-py`` from source, you will need a Rust toolchain installed, as it is a build-time dependency. +An example of how to do so in a ``Dockerfile`` can be found `here `_. + +If you believe you are on a common platform which should have wheels built (i.e. and not need to compile from source), feel free to file an issue or pull request modifying the GitHub action used here to build wheels via ``maturin``. + +Usage +----- + +Methods in general are named similarly to their ``rpds`` counterparts (rather than ``pyrsistent``\ 's conventions, though probably a full drop-in ``pyrsistent``\ -compatible wrapper module is a good addition at some point). + +.. code:: python + + >>> from rpds import HashTrieMap, HashTrieSet, List + + >>> m = HashTrieMap({"foo": "bar", "baz": "quux"}) + >>> m.insert("spam", 37) == HashTrieMap({"foo": "bar", "baz": "quux", "spam": 37}) + True + >>> m.remove("foo") == HashTrieMap({"baz": "quux"}) + True + + >>> s = HashTrieSet({"foo", "bar", "baz", "quux"}) + >>> s.insert("spam") == HashTrieSet({"foo", "bar", "baz", "quux", "spam"}) + True + >>> s.remove("foo") == HashTrieSet({"bar", "baz", "quux"}) + True + + >>> L = List([1, 3, 5]) + >>> L.push_front(-1) == List([-1, 1, 3, 5]) + True + >>> L.rest == List([3, 5]) + True + + +.. toctree:: + :glob: + :hidden: + + api diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000..9fe44c0 --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,9 @@ +file:.#egg=rpds-py +furo +pygments-github-lexers +sphinx-copybutton +sphinx-json-schema-spec +sphinx>5 +sphinxcontrib-spelling>5 +sphinxext-opengraph +url.py diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c91badb --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,89 @@ +# +# This file is autogenerated by pip-compile with Python 3.12 +# by the following command: +# +# pip-compile --strip-extras docs/requirements.in +# +alabaster==0.7.13 + # via sphinx +babel==2.14.0 + # via sphinx +beautifulsoup4==4.12.2 + # via furo +certifi==2023.11.17 + # via requests +charset-normalizer==3.3.2 + # via requests +docutils==0.20.1 + # via sphinx +furo==2023.9.10 + # via -r docs/requirements.in +idna==3.6 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.2 + # via sphinx +lxml==4.9.3 + # via sphinx-json-schema-spec +markupsafe==2.1.3 + # via jinja2 +packaging==23.2 + # via sphinx +pyenchant==3.2.2 + # via sphinxcontrib-spelling +pygments==2.17.2 + # via + # furo + # pygments-github-lexers + # sphinx +pygments-github-lexers==0.0.5 + # via -r docs/requirements.in +requests==2.31.0 + # via sphinx +file:.#egg=rpds-py + # via -r docs/requirements.in +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.5 + # via beautifulsoup4 +sphinx==7.2.6 + # via + # -r docs/requirements.in + # furo + # sphinx-basic-ng + # sphinx-copybutton + # sphinx-json-schema-spec + # sphinxcontrib-applehelp + # sphinxcontrib-devhelp + # sphinxcontrib-htmlhelp + # sphinxcontrib-qthelp + # sphinxcontrib-serializinghtml + # sphinxcontrib-spelling + # sphinxext-opengraph +sphinx-basic-ng==1.0.0b2 + # via furo +sphinx-copybutton==0.5.2 + # via -r docs/requirements.in +sphinx-json-schema-spec==2023.8.1 + # via -r docs/requirements.in +sphinxcontrib-applehelp==1.0.7 + # via sphinx +sphinxcontrib-devhelp==1.0.5 + # via sphinx +sphinxcontrib-htmlhelp==2.0.4 + # via sphinx +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.6 + # via sphinx +sphinxcontrib-serializinghtml==1.1.9 + # via sphinx +sphinxcontrib-spelling==8.0.0 + # via -r docs/requirements.in +sphinxext-opengraph==0.9.1 + # via -r docs/requirements.in +url-py==0.10.0 + # via -r docs/requirements.in +urllib3==2.1.0 + # via requests diff --git a/docs/spelling-wordlist.txt b/docs/spelling-wordlist.txt new file mode 100644 index 0000000..e69de29