feat: add doc

.github/workflows/doc.yml

@@ -0,0 +1,54 @@
+name: "Documentation"
+
+on:
+  push:
+    branches:
+      - "master"
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - "master"
+
+jobs:
+  build:
+    name: Build sphinx documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Install Poetry
+      run: pipx install poetry
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.12
+        cache: "poetry"
+    - name: Setup environment
+      run: poetry install
+    - name: Build HTML
+      run: poetry run sphinx-build -M html docs docs/build
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: github-pages
+        path: docs/build/html/
+  deploy:
+      name: Deploy documentation
+      runs-on: ubuntu-latest
+      needs: build
+      if: startsWith(github.ref, 'refs/tags/v')
+      permissions:
+        pages: write      # to deploy to Pages
+        id-token: write   # to verify the deployment originates from an appropriate source
+      environment:
+        name: github-pages
+        url: ${{ steps.deployment.outputs.page_url }}
+      steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2 # or the latest "vX.X.X" version tag for this action
+
+

README.md

@@ -4,11 +4,9 @@
 
 ![License](https://img.shields.io/pypi/l/immutabledict) ![Build](https://img.shields.io/github/actions/workflow/status/corenting/immutabledict/ci.yml?branch=master) ![Codecov](https://img.shields.io/codecov/c/github/corenting/immutabledict) ![PyPI - Downloads](https://img.shields.io/pypi/dm/immutabledict)
 
-A fork of the original [frozendict](https://github.com/slezica/python-frozendict), an immutable wrapper around dictionaries.
-This library is a pure Python, MIT-licensed alternative to the new LGPL-3.0 licensed [frozendict](https://github.com/Marco-Sulla/python-frozendict).
+An immutable wrapper around dictionaries. immutabledict implements the complete mapping interface and can be used as a drop-in replacement for dictionaries where immutability is desired.
 
-It implements the complete mapping interface and can be used as a drop-in replacement for dictionaries where immutability is desired.
-The immutabledict constructor mimics dict, and all of the expected interfaces (iter, len, repr, hash, getitem) are provided. Note that an immutabledict does not guarantee the immutability of its values, so the utility of hash method is restricted by usage.
+It's a fork of slezica's [frozendict](https://github.com/slezica/python-frozendict). This library is a pure Python, MIT-licensed alternative to the new LGPL-3.0 licensed [frozendict](https://github.com/Marco-Sulla/python-frozendict).
 
 ## Installation
 

docs/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)

docs/api/immutable_ordered_dict.rst

@@ -0,0 +1,7 @@
+ImmutableOrderedDict
+======================
+
+.. autoclass:: immutabledict.ImmutableOrderedDict
+    :exclude-members: dict_cls
+    :show-inheritance:
+    :member-order: bysource

docs/api/immutabledict.rst

@@ -0,0 +1,6 @@
+immutabledict
+======================
+
+.. autoclass:: immutabledict.immutabledict
+    :exclude-members: items,keys,values
+    :member-order: bysource

docs/conf.py

@@ -0,0 +1,52 @@
+"""sphinx configuration."""
+from immutabledict import __version__
+
+# Project info
+project = "immutabledict"
+copyright = "2023, corenting"
+author = "corenting"
+version = __version__
+release = __version__
+
+# General configuration
+extensions = [
+    "alabaster",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autodoc",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# Autodoc settings
+autodoc_default_options = {
+    "members": True,
+}
+
+# intersphinx to Python
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+# HTML output
+html_theme = "alabaster"
+html_sidebars = {
+    "**": [
+        "about.html",
+        "navigation.html",
+        "relations.html",
+        "searchbox.html",
+        "donate.html",
+    ]
+}
+html_theme_options = {
+    "description": "An immutable wrapper around dictionaries",
+    "github_user": "corenting",
+    "github_repo": "immutabledict",
+    "codecov_button": True,
+    "badge_branch": "master",
+    "sidebar_width": "300px",
+    "donate_url": "https://corenting.fr/donate",
+    "extra_nav_links": {
+        "Github repository": "https://github.com/corenting/immutabledict",
+        "PyPI page": "https://pypi.org/project/immutabledict/",
+    },
+}

docs/index.rst

@@ -0,0 +1,31 @@
+Welcome to immutabledict’s documentation!
+=========================================
+
+This site covers immutabledict’s API documentation. For more information about immutabledict, see `the Github repository <https://github.com/corenting/immutabledict>`_.
+
+Usage
+-----
+
+The :class:`.immutabledict`  class can be used as a drop-in replacement for :class:`dict`.
+
+For replacing an :class:`collections.OrderedDict`, you can use an :class:`.ImmutableOrderedDict`. The API is the same as :class:`.immutabledict`, but it will use an :class:`collections.OrderedDict` under the hood.
+
+.. code-block:: python
+
+   from immutabledict import immutabledict
+
+   my_item = immutabledict({"a": "value", "b": "other_value"})
+   print(my_item["a"]) # Print "value"
+
+Some additional methods are provided, see the API reference.
+
+
+API reference
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   /api/immutabledict
+   /api/immutable_ordered_dict
+

immutabledict/__init__.py

@@ -1,3 +1,4 @@
+"""Implementation of the :class:`immutabledict` and :class:`ImmutableOrderedDict` classes."""
 from __future__ import annotations
 
 from collections import OrderedDict
@@ -7,12 +8,12 @@
     ItemsView,
     Iterable,
     Iterator,
+    KeysView,
     Mapping,
     Optional,
     Type,
     TypeVar,
     ValuesView,
-    KeysView,
 )
 
 __version__ = "3.0.0"
@@ -21,27 +22,26 @@
 _V = TypeVar("_V", covariant=True)
 
 
-class immutabledict(Mapping[_K, _V]):
+class immutabledict(Mapping[_K, _V]):  # noqa: N801
     """
-    An immutable wrapper around dictionaries that implements
-    the complete :py:class:`collections.Mapping` interface.
-    It can be used as a drop-in replacement for dictionaries
-    where immutability is desired.
+    An immutable wrapper around dictionaries that implements the complete :py:class:`collections.Mapping` interface.
+
+    It can be used as a drop-in replacement for dictionaries where immutability is desired.
     """
 
-    dict_cls: Type[Dict[Any, Any]] = dict
+    _dict_cls: Type[Dict[Any, Any]] = dict
     _dict: Dict[_K, _V]
     _hash: Optional[int]
 
     @classmethod
-    def fromkeys(
+    def fromkeys(  # noqa: D102
         cls, seq: Iterable[_K], value: Optional[_V] = None
     ) -> immutabledict[_K, _V]:
-        return cls(cls.dict_cls.fromkeys(seq, value))
+        return cls(cls._dict_cls.fromkeys(seq, value))
 
-    def __new__(cls, *args: Any, **kwargs: Any) -> immutabledict[_K, _V]:
+    def __new__(cls, *args: Any, **kwargs: Any) -> immutabledict[_K, _V]:  # noqa: D102
         inst = super().__new__(cls)
-        setattr(inst, "_dict", cls.dict_cls(*args, **kwargs))
+        setattr(inst, "_dict", cls._dict_cls(*args, **kwargs))
         setattr(inst, "_hash", None)
         return inst
 
@@ -51,7 +51,7 @@ def __getitem__(self, key: _K) -> _V:
     def __contains__(self, key: object) -> bool:
         return key in self._dict
 
-    def copy(self) -> immutabledict[_K, _V]:
+    def copy(self) -> immutabledict[_K, _V]:  # noqa: D102
         return self.__class__(self)
 
     def __iter__(self) -> Iterator[_K]:
@@ -61,7 +61,7 @@ def __len__(self) -> int:
         return len(self._dict)
 
     def __repr__(self) -> str:
-        return "{}({!r})".format(self.__class__.__name__, self._dict)
+        return f"{self.__class__.__name__}({self._dict!r})"
 
     def __hash__(self) -> int:
         if self._hash is None:
@@ -89,26 +89,48 @@ def __ror__(self, other: Any) -> Dict[Any, Any]:
     def __ior__(self, other: Any) -> immutabledict[_K, _V]:
         raise TypeError(f"'{self.__class__.__name__}' object is not mutable")
 
-    def items(self) -> ItemsView[_K, _V]:
+    def items(self) -> ItemsView[_K, _V]:  # noqa: D102
         return self._dict.items()
 
-    def keys(self) -> KeysView[_K]:
+    def keys(self) -> KeysView[_K]:  # noqa: D102
         return self._dict.keys()
 
-    def values(self) -> ValuesView[_V]:
+    def values(self) -> ValuesView[_V]:  # noqa: D102
         return self._dict.values()
 
     def set(self, key: _K, value: Any) -> immutabledict[_K, _V]:
+        """
+        Return a new :class:`immutabledict` where the given key is set to to the given value. If the key already exists it will be replaced.
+
+        :param key: the key for which we want to set a value
+        :param value: the value we want to use
+
+        :return: the new :class:`immutabledict` with the key set to the given value
+        """
         new = dict(self._dict)
         new[key] = value
         return self.__class__(new)
 
     def delete(self, key: _K) -> immutabledict[_K, _V]:
+        """
+        Return a new :class:`immutabledict` without the item at the given key.
+
+        :param key: the key of the item you want to remove in the returned :class:`immutabledict`
+
+        :raises [KeyError]: a KeyError is raised if there is no item at the given key
+
+        :return: the new :class:`immutabledict` without the item at the given key
+        """
         new = dict(self._dict)
         del new[key]
         return self.__class__(new)
 
     def update(self, _dict: Dict[_K, _V]) -> immutabledict[_K, _V]:
+        """
+        Similar to :meth:`dict.update` but returning an immutabledict.
+
+        :return: the updated :class:`immutabledict`
+        """
         new = dict(self._dict)
         new.update(_dict)
         return self.__class__(new)
@@ -117,6 +139,8 @@ def update(self, _dict: Dict[_K, _V]) -> immutabledict[_K, _V]:
 class ImmutableOrderedDict(immutabledict[_K, _V]):
     """
     An immutabledict subclass that maintains key order.
+
+    Same as :class:`immutabledict` but based on :class:`collections.OrderedDict`.
     """
 
     dict_cls = OrderedDict