Proper documentation structure

readthedocs.yaml → .readthedocs.yaml

@@ -14,7 +14,7 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-  configuration: docs/conf.py
+  configuration: docs/source/conf.py
   # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
   # builder: "dirhtml"
   # Fail on all warnings to avoid broken references

docs/__init__.py

@@ -1 +1 @@
-""""Init file."""
+"""Init file for docs."""

docs/make.bat

@@ -10,6 +10,8 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=build
 
+if "%1" == "" goto help
+
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
@@ -19,12 +21,10 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
+	echo.http://sphinx-doc.org/
 	exit /b 1
 )
 
-if "%1" == "" goto help
-
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 

docs/source/__init__.py

@@ -1 +1 @@
-"""Init file for source folder."""
+"""Init file for docs source."""

docs/source/api.rst

@@ -0,0 +1,7 @@
+API
+===
+
+.. automodule:: tadoasync
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/conf.py

@@ -1,29 +1,42 @@
-""""Sphinx configuration file for the tadoasync documentation."""
+"""Config file for Sphinx and documentation."""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path("../../src").resolve()))
 # Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+# -- Project information
 
-project = "tadoasync"
+project = "Tado Async"
 copyright = "2024, Erwin Douna"  # noqa: A001
 author = "Erwin Douna"
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+release = "0.1"
+version = "0.1.0"
+
+# -- General configuration
 
 extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
 ]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
 templates_path = ["_templates"]
+autosummary_generate = True
 
+# -- Options for HTML output
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = "sphinx_rtd_theme"
 
-html_theme = "alabaster"
-html_static_path = ["_static"]
+# -- Options for EPUB output
+epub_show_urls = "footnote"

docs/source/index.rst

@@ -1,16 +1,21 @@
-.. tadoasync documentation master file, created by
-   sphinx-quickstart on Mon Jul 15 20:16:26 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Welcome to Tado Async's documentation!
+=======================================
 
-tadoasync documentation
-=======================
+**Tado Async** is a Python library that allows you to control Tado devices.
+Although it can be used as a standalone package, it is current scope is to be used within Home Assistant.
+Not all endpoints and features are fully supported.
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
+Check out the :doc:`usage` section for further information, including
+how to :ref:`installation` the project.
 
+.. note::
+
+   This project is under active development.
+
+Contents
+--------
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+
+   usage
+   api

docs/source/usage.rst

@@ -0,0 +1,32 @@
+Usage
+=====
+
+.. _installation:
+
+Installation
+------------
+
+To use Tado Async, first install it using pip:
+
+.. code-block:: console
+
+   (.venv) $ pip install tadoasync
+
+Example setup
+----------------
+
+.. code-block:: python
+
+    import asyncio
+
+    from tadoasync import Tado
+
+
+    async def main() -> None:
+        """Show example on how to use aiohttp.ClientSession."""
+        async with Tado("username", "password") as tado:
+            await tado.get_devices()
+
+
+    if __name__ == "__main__":
+        asyncio.run(main())