v3.1.0 Documentation (#71)

* Changed docstrings update (#70)

* Added deploy docs (#72)

* Added deploy docs


* Change working version, update docs manually or push to main

* Make docs nicer (#73)

* Changed docstring issues fixed

* Changed sphinx <peter griffin closing curtain gif>

* Add deploy action (#74)

.github/workflows/deploy_docs.yml

@@ -2,32 +2,48 @@ name: Build and Deploy Documentation
 
 on:
   push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
+    branches: ["main"]
   workflow_dispatch:
 
+permissions:
+  id-token: write
+  pages: write
+  contents: read
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
-  build-and-deploy:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
     steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.x'
-
-    - name: Build documentation
-      run: bash scripts/build_docs.sh
-
-    - name: Deploy to GitHub Pages
-      if: github.event_name != 'pull_request'
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./docs/build/html
-        force_orphan: true
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Build documentation
+        run: bash scripts/build_docs.sh
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/build/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      - name: Output documentation URL
+        run: |
+          echo "📚 Documentation URL: ${{ steps.deployment.outputs.page_url }}"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "redis-dict"
-version = "3.0.0"
+version = "3.1.0"
 description = "Dictionary with Redis as storage backend"
 authors = [
     {name = "Melvin Bijman", email = "[email protected]"},
@@ -128,6 +128,6 @@ paths = ["src/redis_dict"]
 
 [project.urls]
 Homepage = "https://github.com/Attumm/redisdict"
-Documentation = "https://github.com/Attumm/redisdict#readme"
+Documentation = "https://attumm.github.io/redis-dict/"
 Repository = "https://github.com/Attumm/redisdict.git"
 Changelog = "https://github.com/Attumm/redisdict/releases"

scripts/build_dev_checks.sh

@@ -1,15 +1,13 @@
 #!/bin/bash
 set -e
 
-rm -rf dev_venv
+rm -rf .venv_dev
 python3 -m venv .venv_dev
 source .venv_dev/bin/activate
 
 pip install --upgrade pip
 pip install -e ".[dev]"
 
-pip freeze > dev-requirements.txt
-
 # Type Check
 python -m mypy
 

scripts/build_docs.sh

@@ -3,7 +3,7 @@ set -e
 
 rm -rf docs/Makefile docs/build/* docs/source/*
 
-#python3 -m venv .venv_docs
+python3 -m venv .venv_docs
 
 source .venv_docs/bin/activate
 pip install --upgrade pip
@@ -17,5 +17,3 @@ sphinx-apidoc -o docs/source src/redis_dict
 
 cd docs
 make html
-
-echo "Documentation built successfully in docs/build/html/"

scripts/generate_sphinx_config.py

@@ -21,11 +21,16 @@ def generate_configs():
 
     docs_path = Path('docs')
     docs_path.mkdir(exist_ok=True)
+
     source_path = docs_path / 'source'
     source_path.mkdir(exist_ok=True)
 
+    module_docs_path = source_path / 'redis_dict'
+    module_docs_path.mkdir(exist_ok=True)
+
     docs_path = Path('docs')
     docs_path.mkdir(exist_ok=True)
+
     source_path = docs_path / 'source'
     source_path.mkdir(exist_ok=True)
 
@@ -59,6 +64,14 @@ def generate_configs():
     'myst_parser',
 ]
 
+# Configure autodoc to show the module source
+autodoc_default_options = {{
+    'members': True,
+    'undoc-members': True,
+    'show-inheritance': True,
+    'special-members': '__init__',
+}}
+
 myst_update_mathjax = False
 myst_enable_extensions = [
     "colon_fence",
@@ -71,46 +84,70 @@ def generate_configs():
 def setup(app):
     print(f"Python path: {{sys.path}}")
 
+html_sidebars = {{
+    '**': [
+        'globaltoc.html',
+        'relations.html',
+        'sourcelink.html',
+        'searchbox.html'
+    ]
+}}
+
+toc_object_entries = True
+toc_object_entries_show_parents = 'domain'
+
 html_theme = 'sphinx_rtd_theme'
 """
 
     index_content = """Redis Dict Documentation
 ========================
 
+.. toctree::
+   :maxdepth: 4
+   :caption: CONTENTS
+
+   modules
+   readme
+
 .. include:: ../../README.md
    :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 2
-   :caption: API Reference
 
-   modules
-   redis_dict
+   redis_dict/core
+   redis_dict/type_management
+"""
 
-Indices and tables
-==================
+    readme_content = """Overview
+========
 
-* :ref:`genindex`
-"""
+    .. include:: ../../README.md
+       :parser: myst_parser.sphinx_
+    """
 
-    index_content1 = """
-Redis Dict Documentation
-=====================
+    core_content = """redis_dict.core module
+======================
 
-.. include:: ../../README.md
-   :parser: myst_parser.sphinx_
+.. automodule:: redis_dict.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+   :noindex:
+    """
 
-.. toctree::
-    :maxdepth: 2
-    :caption: Contents:
 
-    modules
+    type_management = """Redis Dict Type Management
+==============================
 
-Indices and Tables
-================
+.. automodule:: redis_dict.type_management
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex:
+    """
 
-* :ref:`genindex`
-"""
 
     makefile_content = """
 # Minimal makefile for Sphinx documentation
@@ -131,12 +168,20 @@ def setup(app):
     with open(source_path / 'conf.py', 'w') as f:
         f.write(conf_content)
 
+    with open(docs_path / 'Makefile', 'w') as f:
+        f.write(makefile_content)
+
     with open(source_path / 'index.rst', 'w') as f:
         f.write(index_content)
 
-    with open(docs_path / 'Makefile', 'w') as f:
-        f.write(makefile_content)
+    with open(source_path / 'readme.rst', 'w') as f:
+        f.write(readme_content)
+
+    with open(module_docs_path / 'core.rst', 'w') as f:
+        f.write(core_content)
 
+    with open(module_docs_path / 'type_management.rst', 'w') as f:
+        f.write(type_management)
 
 if __name__ == '__main__':
     generate_configs()

src/redis_dict/core.py

@@ -35,13 +35,6 @@ class RedisDict:
     This functionality enables various use cases, such as managing encrypted data in Redis,
     To implement this, simply create and register your custom encoding and decoding functions.
     By delegating serialization to redis-dict, reduce complexity and have simple code in the codebase.
-
-    Attributes:
-        decoding_registry (Dict[str, DecodeFuncType]): Mapping of decoding transformation functions based on type
-        encoding_registry (Dict[str, EncodeFuncType]): Mapping of encoding transformation functions based on type
-        namespace (str): A string used as a prefix for Redis keys to separate data in different namespaces.
-        expire (Union[int, None]): An optional expiration time for keys, in seconds.
-
     """
 
     encoding_registry: EncodeType = enc_reg
@@ -53,7 +46,8 @@ def __init__(self,
                  preserve_expiration: Optional[bool] = False,
                  redis: "Optional[StrictRedis[Any]]" = None,
                  **redis_kwargs: Any) -> None:
-        """Initialize a RedisDict instance.
+        """
+        Initialize a RedisDict instance.
 
         Init the RedisDict instance.
 
@@ -220,7 +214,8 @@ def extends_type(
             encoding_method_name: Optional[str] = None,
             decoding_method_name: Optional[str] = None,
     ) -> None:
-        """Extend RedisDict to support a custom type in the encode/decode mapping.
+        """
+        Extend RedisDict to support a custom type in the encode/decode mapping.
 
         This method enables serialization of instances based on their type,
         allowing for custom types, specialized storage formats, and more.
@@ -247,19 +242,19 @@ def extends_type(
         attributes of the RedisDict instance
 
         Example:
-            class Person:
-                def __init__(self, name, age):
-                    self.name = name
-                    self.age = age
-
-                def encode(self) -> str:
-                    return json.dumps(self.__dict__)
-
-                @classmethod
-                def decode(cls, encoded_str: str) -> 'Person':
-                    return cls(**json.loads(encoded_str))
-
-            redis_dict.extends_type(Person)
+            >>> class Person:
+            ...     def __init__(self, name, age):
+            ...         self.name = name
+            ...         self.age = age
+            ...
+            ...     def encode(self) -> str:
+            ...         return json.dumps(self.__dict__)
+            ...
+            ...     @classmethod
+            ...     def decode(cls, encoded_str: str) -> 'Person':
+            ...         return cls(**json.loads(encoded_str))
+            ...
+            >>> redis_dict.extends_type(Person)
 
         Args:
             class_type (type): The class `__name__` will become the key for the encoding and decoding functions.
@@ -409,8 +404,8 @@ def __str__(self) -> str:
         return str(self.to_dict())
 
     def __or__(self, other: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        Implements the | operator (dict union).
+        """Implement the | operator (dict union).
+
         Returns a new dictionary with items from both dictionaries.
 
         Args:
@@ -432,7 +427,8 @@ def __or__(self, other: Dict[str, Any]) -> Dict[str, Any]:
 
     def __ror__(self, other: Dict[str, Any]) -> Dict[str, Any]:
         """
-        Implements the reverse | operator.
+        Implement the reverse | operator.
+
         Called when RedisDict is on the right side of |.
 
         Args:
@@ -454,7 +450,8 @@ def __ror__(self, other: Dict[str, Any]) -> Dict[str, Any]:
 
     def __ior__(self, other: Dict[str, Any]) -> 'RedisDict':
         """
-        Implements the |= operator (in-place union).
+        Implement the |= operator (in-place union).
+
         Modifies the current dictionary by adding items from other.
 
         Args:
@@ -475,7 +472,7 @@ def __ior__(self, other: Dict[str, Any]) -> 'RedisDict':
     @classmethod
     def __class_getitem__(cls: Type['RedisDict'], key: Any) -> Type['RedisDict']:
         """
-        Enables type hinting support like RedisDict[str, Any].
+        Enable type hinting support like RedisDict[str, Any].
 
         Args:
             key (Any): The type parameter(s) used in the type hint.
@@ -487,7 +484,8 @@ def __class_getitem__(cls: Type['RedisDict'], key: Any) -> Type['RedisDict']:
 
     def __reversed__(self) -> Iterator[str]:
         """
-        Implements reversed() built-in:
+        Implement reversed() built-in.
+
         Returns an iterator over dictionary keys in reverse insertion order.
 
         Warning: