Skip to content

Commit 03cbfd0

Browse files
bookman-diusbookman-dius
committed
first pass at documentation
1 parent cf6f742 commit 03cbfd0

File tree

10 files changed

+286
-1
lines changed

10 files changed

+286
-1
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Deploy Documentation to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [ "main" ]
6+
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v5
24+
25+
- name: Set up Python
26+
uses: actions/setup-python@v6
27+
with:
28+
python-version: '3.12'
29+
30+
- name: Install dependencies
31+
run: |
32+
pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
33+
34+
- name: Build documentation
35+
run: |
36+
cd docs
37+
make html
38+
39+
- name: Setup Pages
40+
uses: actions/configure-pages@v4
41+
42+
- name: Upload artifact
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: 'docs/build/html'
46+
47+
deploy:
48+
runs-on: ubuntu-latest
49+
needs: build
50+
steps:
51+
- name: Deploy to GitHub Pages
52+
id: deployment
53+
uses: actions/deploy-pages@v4

‎custom_components/powersensor/manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
],
88
"config_flow": true,
99
"dependencies": [],
10-
"documentation": "https://github.com/DiUS/homeassistant-powersensor",
10+
"documentation": "https://dius.github.io/homeassistant-powersensor/",
1111
"homekit": {},
1212
"integration_type" : "hub",
1313
"iot_class": "local_push",

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
build/

‎docs/Makefile‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Minimal makefile for Sphinx documentation
2+
3+
SPHINXOPTS ?=
4+
SPHINXBUILD ?= sphinx-build
5+
SOURCEDIR = source
6+
BUILDDIR = build
7+
8+
help:
9+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
10+
11+
.PHONY: help Makefile
12+
13+
%: Makefile
14+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.https://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/_static/powersensor-logo.png‎

3.67 KB
Loading

‎docs/source/conf.py‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
"""Sphinx configuration file for homeassistant_powersensor documentation."""
2+
3+
import sys
4+
from pathlib import Path
5+
6+
# Add the package to the Python path
7+
project_root = Path(__file__).parent.parent.parent
8+
sys.path.insert(0, str(project_root / "custom_components"))
9+
print(project_root)
10+
11+
# Project information
12+
project = "homeassistant-powersensor"
13+
copyright = "2025, DiUS"
14+
author = "Powersensor Team!"
15+
16+
html_favicon = "_static/powersensor-logo.png"
17+
html_logo = "_static/powersensor-logo.png"
18+
19+
20+
release = "0.0.1"
21+
22+
version = ".".join(release.split(".")[:2])
23+
24+
# Extensions
25+
extensions = [
26+
"sphinx.ext.autodoc",
27+
"sphinx.ext.viewcode",
28+
"sphinx.ext.napoleon",
29+
"sphinx.ext.intersphinx",
30+
"sphinx_autodoc_typehints",
31+
"sphinx.ext.autosummary"
32+
]
33+
34+
# Napoleon settings (for Google and NumPy style docstrings)
35+
napoleon_google_docstring = True
36+
napoleon_numpy_docstring = True
37+
napoleon_include_init_with_doc = False
38+
napoleon_include_private_with_doc = False
39+
40+
# Autodoc settings
41+
autodoc_default_options = {
42+
"members": True,
43+
"undoc-members": True,
44+
"show-inheritance": True,
45+
}
46+
47+
# Intersphinx mapping
48+
intersphinx_mapping = {
49+
"python": ("https://docs.python.org/3", None),
50+
}
51+
52+
# HTML theme
53+
html_theme = "sphinx_rtd_theme"
54+
html_static_path = ["_static"]
55+
html_css_files = []
56+
57+
58+
# Output file base name for HTML help builder
59+
htmlhelp_basename = "homeassistant_powersensor_doc"
60+
61+
# Options for LaTeX output
62+
latex_elements = {}
63+
latex_documents = [
64+
("index", "homeassistant_powersensor.tex", "homeassistant_powersensor Documentation", "Your Name", "manual"),
65+
]
66+
67+
# Options for manual page output
68+
man_pages = [
69+
("index", "homeassistant_powersensor", "homeassistant_powersensor Documentation", [author], 1)
70+
]
71+
72+
# Options for Texinfo output
73+
texinfo_documents = [
74+
(
75+
"index",
76+
"homeassistant_powersensor",
77+
"homeassistant_powersensor Documentation",
78+
author,
79+
"homeassistant_powersensor",
80+
"One line description of project.",
81+
"Miscellaneous",
82+
),
83+
]

‎docs/source/data.rst‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
Data Available in ``homeassistant-powersensor``
2+
================================================
3+
The data provided in the home assistant integration should be reflective of exactly the data available
4+
in the devices screen of the powersensor app with the exception of the top level view provided by the virtual
5+
household
6+
7+
Virtual Household
8+
------------------
9+
Built on top of the sensors, the API provided by `powersensor_local <https://github.com/DiUS/python-powersensor_local>`_
10+
provides a ``virtual household``. This view is captures the key data most users want to capture at the household level
11+
This includes
12+
13+
* Energy imported from the grid
14+
* Total home energy usage
15+
* Energy exported to the grid (from solar)
16+
* Total solar production
17+
18+
As well as the corresponding instantaneous power consumption/production.
19+
20+
Plugs
21+
-----
22+
Each plug exposes 6 entities reflecting the different measurements made by the plug these are
23+
24+
* Active Current
25+
* Apparent Current
26+
* Power
27+
* Reactive Current
28+
* Total Energy Consumption
29+
* Voltage
30+
31+
This is the full extend of data available via the plug api, but much of this data is redundant and future
32+
releases intend to make these optional selections when the integration is configured
33+
34+
35+
Sensors
36+
-------
37+
38+
Each sensor exposes
39+
40+
* Sensor battery level
41+
* Power
42+
* Total Energy
43+
44+
Any of these entities can be used in automation workflows

‎docs/source/index.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Welcome to homeassistant-powersensor's Documentation
2+
====================================================
3+
This package provides a `Home Assistant <https://www.home-assistant.io/>`_
4+
integration for `Powersensor <https://www.powersensor.com.au/>`_ devices,
5+
and is primarily a wrapper around the `powersensor_local <https://dius.github.io/python-powersensor_local/>`_ API
6+
allowing access to for data from Powersensor devices in Home Assistant.
7+
8+
This integration enables users to view their local powersensor data within home assistant as well as exposing
9+
various sensors that can be used for home automation and interfaces with other smart devices.
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: Contents:
14+
15+
installation
16+
data
17+
18+
19+
Indices and tables
20+
==================
21+
22+
* :ref:`genindex`
23+
* :ref:`search`

‎docs/source/installation.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
Installation
2+
============
3+
4+
In its current form, the only supported installation method for the ``homeassistant-powersensor`` integration is
5+
manual. In the near future, we intend to support installation via `HACS <https://hacs.xyz/>`_
6+
however that is not yet possible.
7+
8+
Prerequisites
9+
--------------
10+
Before installing this integration, ensure you have:
11+
12+
* Home Assistant 2024.1.0 or newer
13+
* Access to your Home Assistant configuration directory
14+
* `powersensor_local <https://github.com/DiUS/python-powersensor_local>`_ 2.0.0 or later installed in your Home Assistant instance's python environment
15+
* Firmware updated to version 8107 or later on powersensor hardware (plugs and sensors)
16+
17+
From Source
18+
------------
19+
Clone or download this repo e.g
20+
.. code-block:: bash
21+
22+
git clone https://github.com/DiUS/homeassistant-powersensor.git
23+
24+
Copy or symlink the directory ``custom_components/powersensor`` to your Home Assistant configuration directory.
25+
When launching homeassistant, e.g.
26+
.. code-block:: bash
27+
28+
hass --config ./config
29+
30+
Home assistant should automatically discover powersensor devices on the same network.
31+
Follow the links for Settings/Devices&Services. At the top you should be prompted add ``powersensor`` to your
32+
homeassistant instance.

0 commit comments

Comments
 (0)