Skip to content

Commit

Permalink
Simple docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
Julian committed Dec 17, 2023
1 parent 67717ab commit d0ba48e
Show file tree
Hide file tree
Showing 9 changed files with 272 additions and 0 deletions.
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -70,3 +70,9 @@ docs/_build/

# Pyenv
.python-version

# User defined
/dirhtml
_cache

TODO
17 changes: 17 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://docs.rs/rpds/>`_ for persistent data structures.

Expand Down
8 changes: 8 additions & 0 deletions docs/api.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
API Reference
=============

.. automodule:: rpds
:members:
:undoc-members:
:imported-members:
:special-members: __iter__, __getitem__, __len__, __rmatmul__
87 changes: 87 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -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
52 changes: 52 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
Python bindings to the `Rust rpds crate <https://docs.rs/rpds/>`_ for persistent data structures.

What's here is quite minimal (in transparency, it was written initially to support replacing ``pyrsistent`` in the `referencing library <https://github.com/python-jsonschema/referencing>`_).
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 <https://github.com/bowtie-json-schema/bowtie/blob/e77fd93598cb6e7dc1b8b1f53c00e5aa410c201a/implementations/python-jsonschema/Dockerfile#L1-L8>`_.

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
9 changes: 9 additions & 0 deletions docs/requirements.in
Original file line number Diff line number Diff line change
@@ -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
89 changes: 89 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -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
Empty file added docs/spelling-wordlist.txt
Empty file.

0 comments on commit d0ba48e

Please sign in to comment.