Modernize docs

.github/workflows/test-suite.yml

@@ -6,8 +6,7 @@ on:
       - "pyproject.toml"
   pull_request:
     branches:
-      - master
-      - dev
+      - main
     paths:
       - "**.py"
       - "pyproject.toml"

README.md

@@ -1,13 +1,13 @@
 # HomeassistantAPI
 
-[![Code Coverage](https://img.shields.io/codecov/c/github/GrandMoff100/HomeAssistantAPI/dev?style=for-the-badge&token=SJFC3HX5R1)](https://codecov.io/gh/GrandMoff100/HomeAssistantAPI)
+[![Code Coverage](https://img.shields.io/codecov/c/github/HomeAssistant-API/HomeAssistantAPI/dev?style=for-the-badge&token=SJFC3HX5R1)](https://codecov.io/gh/HomeAssistant-API/HomeAssistantAPI)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/HomeAssistant-API?style=for-the-badge)](https://pypistats.org/packages/homeassistant-api)
-![GitHub commits since latest release (by date including pre-releases)](https://img.shields.io/github/commits-since/GrandMoff100/HomeassistantAPI/latest/dev?include_prereleases&style=for-the-badge)
+![GitHub commits since latest release (by date including pre-releases)](https://img.shields.io/github/commits-since/HomeAssistant-API/HomeAssistantAPI/latest/dev?include_prereleases&style=for-the-badge)
 [![Read the Docs (version)](https://img.shields.io/readthedocs/homeassistantapi?style=for-the-badge)](https://homeassistantapi.readthedocs.io/en/latest/?badge=latest)
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/GrandMoff100/HomeassistantAPI?style=for-the-badge)](https://github.com/GrandMoff100/HomeassistantAPI/releases)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/HomeAssistant-API/HomeAssistantAPI?style=for-the-badge)](https://github.com/HomeAssistant-API/HomeAssistantAPI/releases)
 
 <a href="https://home-assistant.io">
-    <img src="https://github.com/GrandMoff100/HomeAssistantAPI/blob/7edb4e6298d37bda19c08b807613c6d351788491/docs/images/homeassistant-logo.png?raw=true" width="80%">
+    <img src="https://github.com/HomeAssistant-API/HomeAssistantAPI/blob/7edb4e6298d37bda19c08b807613c6d351788491/docs/images/homeassistant-logo.png?raw=true" width="80%">
 </a>
 
 ## Python wrapper for Homeassistant's [Websocket API](https://developers.home-assistant.io/docs/api/websocket/) and [REST API](https://developers.home-assistant.io/docs/api/rest/)
@@ -65,7 +65,7 @@ you'd want to know is on our readthedocs site [here](https://homeassistantapi.re
 If there is something missing, open an issue and let us know! Thanks!
 
 Go make some cool stuff! Maybe come back and tell us about it in a
-[discussion](https://github.com/GrandMoff100/HomeAssistantAPI/discussions)?
+[discussion](https://github.com/HomeAssistant-API/HomeAssistantAPI/discussions)?
 We'd love to hear about how you use our library!!
 
 ## License

docs/CONTRIBUTING.rst

@@ -11,7 +11,12 @@ Contribution Ideas
 *********************
 
 If you don't know what you want to contribute yet you should take a look at our :resource:`issues page <issues>`.
-See what other people have been up to and if you have an idea for a new feature or a new way to implement a feature you should :resource:`create an issue <issues>` or :resource:`fork the repository <repo>` and start contributing.
+Some other places to start with are:
+
+- **Writing and Rewriting Documentation**--- As more code changes happen and this library continues to mature, more features get added which need documenting.
+- **Adding examples**--- We'd appreciate more self-contained examples that show common use cases.
+
+See what other people have been up to all across the home assistant community and if you have an idea for a new feature you should :resource:`create an issue <issues>` or :resource:`fork the repository <repo>` and start contributing.
 We're always interested in integrating ways to make the library faster, extensible and easier to use.
 
 Setting up your Development Environment
@@ -22,7 +27,7 @@ So now that you know what you want to contribute it is time to setup a developme
 Step One: Fork the Repository
 ===============================
 
-Click `here <https://github.com/GrandMoff100/HomeAssistantAPI/fork>`__ to fork the repository.
+Click :resource:`here <fork>` to fork the repository.
 Then click your username.
 
 Step Two: Clone the Repository Locally
@@ -38,21 +43,54 @@ Step Three: Installing Dependencies
 ======================================
 
 Firstly, you need to have Python 3.11 or newer installed.
-Download the latest Python Version from `here <https://www.python.org/>`__.
+Download the latest Python Version from `here <https://www.python.org/>`__ (or your usual method of installation).
 Then you need to install :code:`uv`, a fast Python package manager.
 Checkout the `uv Docs <https://docs.astral.sh/uv/>`__.
 You can install it with :code:`pip` by running :code:`pip install uv`, or see the uv docs for other installation methods.
 Now you can install the project's dependencies by running :code:`cd HomeAssistantAPI && uv sync`
 
-Step Four: [Optional] Setting Up a Home Assistant Development Environment.
+Step Four: [Optional] Setting Up a Home Assistant Server
 =============================================================================
 
+Option A. Have a Home Assistant installation running.
+------------------------------------------------------
+
+If you already have a Home Assistant installation running, you can use it for development.
+You'll just need to have the API URL and a Long-Lived Access Token available like you would to use the library normally.
+
+
+Option B. Setup a Home Assistant Development Environment.
+----------------------------------------------------------
+
 If you do not have a Home Assistant installation running already, you can setup a Home Assistant Development environment.
-Which is basically a local, unpackaged, Home Assistant Core installation, that runs with just Python (no Docker or Operating System).
+This is basically a local, unpackaged, Home Assistant Core installation, that runs with just Python (no Docker or Operating System).
 You can start and stop the server really easily as it runs just in your
-terminal and gives you lots of control over it, making it ideal for testing your changes to Home Assistant API.
+terminal and gives you control over it, making it ideal for quickly testing your changes.
 Follow this great guide `here <https://developers.home-assistant.io/docs/development_environment>`__ to do that.
-After that you are now ready to make your changes to the codebase!
+You'll access the web dashboard to create the Long-Lived Access Token.
+
+
+Option C. Use a Docker-based Development Environment.
+-----------------------------------------------------
+
+If you prefer to use Docker, you can use your own Docker setup to run a Home Assistant development environment.
+There is also a Dockerfile and compose file that comes with the repository to make it convenient to spin up a development environment.
+To do so, you can run
+
+.. code-block:: bash
+
+   $ docker compose up server
+
+which spins up a container running Home Assistant with port 8123 exposed to your local machine.
+You'll need the following environment variables set to use the repository docker setup:
+
+.. code-block:: bash
+
+   HOMEASSISTANTAPI_URL=http://localhost:8123/api
+   HOMEASSISTANTAPI_WS_URL=ws://localhost:8123/api/websocket
+   HOMEASSISTANTAPI_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkMDE4YjQ4YzMyZTE0ODNhYjY2ZWQzOTZmYzg3ZDAyNiIsImlhdCI6MTY3ODU3NDUwMSwiZXhwIjoxOTkzOTM0NTAxfQ.fyhnfwpont4uE0gn46_Ut_pPmyn4QWv0MDaVAei2PPk
+
+
 
 Testing
 ********
@@ -95,20 +133,20 @@ If you add a new test that makes real HTTP or WebSocket requests, you need to re
 Code Styling Guidelines
 **************************
 
-In order to make sure that our code is easy to read, and navigate.
-As well as to stop stupid mistakes like typos, undefined variables, etc.
-We enforce code standards.
+In order to make sure that our code is easy to read, and navigate
+as well as to stop stupid mistakes like typos, undefined variables, etc,
+we enforce code standards.
 Using the tools, :code:`ruff`, :code:`zuban`, and :code:`pytest`, we make sure that our code quality is top notch and that changes work everywhere.
-You can those tools manually yourself, but they also run automatically when you open a PR.
+You can run those tools manually yourself, but they also run automatically when you open a Pull Request on :resource:`GitHub <repo>`.
+
 
 Merging Your Contributions
 *****************************
 
 Once you have tested your changes and committed them to your fork you can merge them back into the :resource:`original repository <repo>`.
-Head over to the :resource:`Pull Request Page <new_pr>` and select your fork to merge into the `GrandMoff100/dev` branch.
+Head over to the :resource:`Pull Request Page <new_pr>` and select your fork to merge into the main branch.
 Then you can hit "Create Pull Request" and we'll review it as soon as possible.
-In order to be merged though, your code needs to follow our :ref:`Styling Guidelines <styling>`.
-A Github Actions workflow will run on your PR automatically to verify that it does follow the guidelines.
-Then once the checks have passed one of our maintainers will review the changes (basically to make sure your changes won't break anything ;)).
+In order to be merged, a Github Actions workflow will run on your PR automatically, to check that your code passes the styling checks and tests.
+Then once the checks have passed, one of our maintainers will review the changes and ask for clarification or changes (if needed).
 Then after that your changes will get merged and will be available in the next release!
 

docs/_static/css/custom.css

@@ -73,4 +73,9 @@ body {
 
 .version {
     color: #d9d9d9;
+}
+
+table.docutils {
+    margin-bottom: 1.5em !important;
+    margin-left: 0 !important;
 }

docs/advanced.rst

@@ -5,37 +5,48 @@ Advanced Section
 Caching
 **********
 
-By default, caching is **disabled**. You can enable the built-in in-memory cache by passing :code:`use_cache=True`:
+The packaged :py:class:`Client` and :py:class:`AsyncClient` do not come with any built-in caching.
+A convenient option is to use the :py:class:`niquests_cache.session.CachedSession` or :py:class:`niquests_cache.session.AsyncCachedSession` classes from the `niquests_cache` library.
+
 
 .. code-block:: python
 
     from homeassistant_api import Client
 
-    client = Client("<API_URL>", "<TOKEN>", use_cache=True)
+    from niquests_cache.session import CachedSession
+    from niquests_cache.backend import MemoryBackend
+
+    client = Client("<API_URL>", "<TOKEN>", session=CachedSession(backend=MemoryBackend(), expire_after=300))
+
+.. code-block:: python
+
+    from homeassistant_api import AsyncClient
+
+    from niquests_cache.session import AsyncCachedSession
+    from niquests_cache.backend import MemoryBackend
+
+    client = AsyncClient("<API_URL>", "<TOKEN>", session=AsyncCachedSession(backend=MemoryBackend(), expire_after=300))
+
+
+This creates an in-memory cache that expires after 300 seconds. You can adjust the `expire_after` value to fit your needs or set it to `-1` to disable expiration.
+For more information on the available caching options, see the `niquests_cache <https://niquests-cache.readthedocs.io/en/stable/>`__ documentation.
 
-This creates an in-memory cache that expires after 300 seconds.
 
 Persistent Caching
 ********************
 
 If you want your cache to persist between runs (e.g. to a filesystem), you can pass your own custom cached session via the :code:`session` parameter.
 
-Depending on whether you are using a sync or async client you will want to use either :py:class:`requests_cache.CachedSession` or :py:class:`aiohttp_client_cache.session.CachedSession` respectively.
-See the docs for `requests_cache <https://requests-cache.readthedocs.io/en/latest/>`__ and `aiohttp_client_cache <https://aiohttp-client-cache.readthedocs.io/en/latest/>`__ for backend options and more.
-
 .. code-block:: python
 
-    from datetime import timedelta
+    from pathlib import Path
     from homeassistant_api import Client
-    from requests_cache import CachedSession
+    from niquests_cache.session import CachedSession
 
     client = Client(
         "<API_URL>",
         "<TOKEN>",
-        session=CachedSession(
-            backend="filesystem",
-            expire_after=timedelta(minutes=5),
-        ),
+        session=CachedSession(cache_name=Path('.cache') / 'http'),  # by default uses sqlite backend
     )
 
     with client:
@@ -46,17 +57,15 @@ See the docs for `requests_cache <https://requests-cache.readthedocs.io/en/lates
 
     # Or an example for async
     import asyncio
-    from datetime import timedelta
+    from pathlib import Path
     from homeassistant_api import AsyncClient
-    from aiohttp_client_cache import CachedSession, FileBackend
+    from niquests_cache.session import AsyncCachedSession
 
     client = AsyncClient(
         "<API_URL>",
         "<TOKEN>",
-        session=CachedSession(
-            cache=FileBackend(
-                expire_after=timedelta(minutes=5),
-            ),
+        session=AsyncCachedSession(
+            cache_name=Path('.cache') / 'http',
         ),
     )
 
@@ -68,7 +77,7 @@ See the docs for `requests_cache <https://requests-cache.readthedocs.io/en/lates
     asyncio.run(main())
 
 
-Why the heck is :py:class:`Client` a context manager?
+Why is :py:class:`Client` a context manager?
 ********************************************************
 
 The :py:class:`Client` is a context manager because it manages the underlying HTTP session and pings Home Assistant to make sure it's running.

docs/api.rst

@@ -1,7 +1,93 @@
 Code Reference
 ***************
 
-.. automodule:: homeassistant_api
-      :platform: Linux, Windows, MacOS
-      :inherited-members:
-      :exclude-members: model_json_schema, model_copy, model_rebuild, model_dump, construct, copy, dict, from_orm, json, parse_file, model_validate, parse_raw, parse_obj, parse_str, parse_url, schema, schema_json, schema_yaml, schema_yml, to_orm, update_forward_refs, validate, validate_file, validate_obj, validate_raw, validate_str, validate_url, model_validate_strings, model_validate_json, model_validate, model_post_init, model_parametrized_name, model_extra, model_fields_set, model_dump_json, model_construct, model_computed_fields
+Here you can find a detailed reference for most classes and methods in the library.
+
+
+Clients
+=======
+
+.. autoclass:: homeassistant_api.Client
+   :members:
+
+
+.. autoclass:: homeassistant_api.AsyncClient
+   :members:
+
+.. autoclass:: homeassistant_api.BaseClient
+
+
+.. autoclass:: homeassistant_api.WebsocketClient
+   :members:
+
+.. autoclass:: homeassistant_api.AsyncWebsocketClient
+   :members:
+
+.. autoclass:: homeassistant_api.BaseWebsocketClient
+   :members:
+
+
+Data Models
+===========
+
+
+Domain
+--------
+
+.. automodule:: homeassistant_api.models.domains
+   :members:
+   :inherited-members:
+
+Entity
+--------
+
+.. automodule:: homeassistant_api.models.entity
+   :members:
+   :inherited-members:
+
+
+Event
+-------
+
+.. automodule:: homeassistant_api.models.events
+   :members:
+   :inherited-members:
+
+History
+--------
+
+.. automodule:: homeassistant_api.models.history
+   :members:
+   :inherited-members:
+
+Logbook
+--------
+
+.. automodule:: homeassistant_api.models.logbook
+   :members:
+   :inherited-members:
+
+State
+--------------
+
+.. automodule:: homeassistant_api.models.states
+   :members:
+
+Websocket Models
+----------------
+
+.. automodule:: homeassistant_api.models.websocket
+   :members:
+
+Request Processing
+==================
+
+.. automodule:: homeassistant_api.processing
+   :members:
+
+
+Errors
+=======
+
+.. automodule:: homeassistant_api.errors
+   :members: