Renaming, reordering, tidying up

docs/car-charge-planning.md

@@ -15,4 +15,6 @@ There are two ways to plan car charging slots:
     - Enable **car_charging_plan_smart** if you want to use the cheapest slots only
     - Use an automation based on **binary_sensor.predbat_car_charging_slot** to control when your car charges
 
-NOTE: Multiple cars can be planned with Predbat, see the planned car charging section below in this guide.
+NOTE: Multiple cars can be planned with Predbat.
+
+See [Car charging filtering](config-yml-settings.md#car-charging-filtering) and [Planned car charging](config-yml-settings.md#planned-car-charging) in the [config.yml settings](config-yml-settings.md) section of the documentation.

docs/customisation.md

@@ -1,15 +1,15 @@
-# Customisation 
+# Customisation
 
 These are configuration items that you can modify to fit your needs, you can configure these in Home Assistant directly.
 Changing the items in apps.yml will have no effect.
 
-Each config item has an input_number or switch associated with it, see the example dashboard for their exact names ([https://github.com/springfall2008/batpred/blob/main/example_dashboard.yml](https://github.com/springfall2008/batpred/blob/main/example_dashboard.yml))
-
-You can also create a card using 'dynamic-entities-card.yaml' for a dynamically created list of entities for predbat which groups the entities by type and is collapsed by default to prevent screen clutter. Requires lovelace-collapsable-cards ([https://github.com/RossMcMillan92/lovelace-collapsable-cards](https://github.com/RossMcMillan92/lovelace-collapsable-cards)) and lovelace-auto-entities ([https://github.com/thomasloven/lovelace-auto-entities](https://github.com/thomasloven/lovelace-auto-entities)) to be installed via HACS as well as the stock vertical stack card. Credit @DJBenson for the code.
+See [Displaying output data](output-data.md#displayng-output-data)
+for information on how to view and edit these entities within
+Home Assistant.
 
 ## Performance related
 
-By default Predbat controls the inverter and updates the plan every 5 minutes, this can however use a lot of CPU power especially on more complex tariffs like Agile when run on lower power machines such as Rasperry PIs and some thin clients.
+By default Predbat controls the inverter and updates the plan every 5 minutes, this can however use a lot of CPU power especially on more complex tariffs like Agile when run on lower power machines such as Raspberry PIs and some thin clients.
 
 You can tweak **input_number.predbat_calculate_plan_every** to reduce the frequency of replanning while keeping the inverter control in the 5 minute slots. E.g. a value of 10 or 15 minutes should also give good results.
 
@@ -38,10 +38,10 @@ e.g. a value of 1.1 would simulate a 10% faster charge/discharge than reported b
 Use 1.0 to use exactly previous load data (1.1 would add 10% to load)
 
 **pv_scaling** is a scaling factor applied to pv data, tune down if you want to be more pessimistic on PV production vs Solcast
-Use 1.0 to use exactly the solcast data (0.9 would remove 10% from forecast)
+Use 1.0 to use exactly the Solcast data (0.9 would remove 10% from forecast)
 
 **pv_metric10_weight** is the weighting given to the 10% PV scenario. Use 0.0 to disable this.
-A value of 0.1 assumes that 1:10 times we get the 10% scenario and hence to count this in the metric benefit/cost. 
+A value of 0.1 assumes that 1:10 times we get the 10% scenario and hence to count this in the metric benefit/cost.
 A value of 0.15 is recommended.
 
 ## Historical load data
@@ -66,7 +66,7 @@ For more accurate results can you use an incrementing energy sensor set with **c
 
 ## Car charging plan options
 
-Car charging planning - is only used if Intelligent Octopus isn't enabled and car_charging_planned is connected correctly. 
+Car charging planning - is only used if Intelligent Octopus isn't enabled and car_charging_planned is connected correctly.
 
 This feature allows Predbat to create a plan for when you car will charge, but you will have to create an automation to trigger your car to charge using **binary_sensor.predbat_car_charging_slot** if you want it to match the plan.
 
@@ -78,7 +78,7 @@ you must have set **octopus_intelligent_slot** sensor in apps.yml to enable this
 
 ## Calculation options
 
-**switch.predbat_calculate_best** When enables tells Predbat to work out the best battery SOC % based on cost, when disabled no scenarios apart from the default settings are computed. 
+**switch.predbat_calculate_best** When enables tells Predbat to work out the best battery SOC % based on cost, when disabled no scenarios apart from the default settings are computed.
 This must be enabled to get all the 'best' sensors.
 
 **switch.predbat_calculate_best_charge** If set to False then charge windows will not be calculated and the default inverter settings are used, when True predbat will decide the charge window automatically.
@@ -111,7 +111,7 @@ A better plan is achieved leaving this false but it can speed up run time to hav
 
 **metric_min_improvement** sets the minimum cost improvement that it's worth lowering the battery SOC % for.
 If it's 0 then this is disabled and the battery will be charged less if it's cost neutral.
-If you use **pv_metric10_weight** then you probably don't need to enable this as the 10% forecast does the same thing better 
+If you use **pv_metric10_weight** then you probably don't need to enable this as the 10% forecast does the same thing better
 Do not use if you have multiple charge windows in a given period as it won't lead to good results (e.g. Agile)
 You could even go to something like -0.1 to say you would charge less even if it cost up to 0.1p more (best used with metric10)
 
@@ -120,7 +120,7 @@ You could even go to something like -0.1 to say you would charge less even if it
 **rate_low_threshold** sets the threshold below average rates as the minimum to consider for a charge window, 0.8 = 80% of average rate
 If you set this too low you might not get enough charge slots. If it's too high you might get too many in the 24-hour period which makes optimisation harder. You can set this to 0 for automatic rate selection when combined with setting **calculate_max_windows** to a lower number e.g. 24 or 32.
 
-**rate_low_match_export** When enabled consider import rates that are lower than the highest export rate (minus any battery losses). 
+**rate_low_match_export** When enabled consider import rates that are lower than the highest export rate (minus any battery losses).
 This is if you want to be really aggressive about importing just to export, default is False (recommended).
 
 **rate_high_threshold** Sets the threshold above average rates as to the minimum export rate to consider exporting for - 1.2 = 20% above average rate
@@ -140,7 +140,7 @@ If you set this too high you might not get any export slots. If it's too low you
 
 **set_charge_window** When enabled the next charge window will be automatically configured based on the incoming rates
 Only works if the charging time window has been enabled and import rates are configured with the rates_import or using Octopus import
-Will also automatically disable charging if not required and re-enable it when required. 
+Will also automatically disable charging if not required and re-enable it when required.
 If you turn this off later check that 'GivTCP Enable Charge Schedule' is turned back on.
 
 **set_window_minutes** defines how many minutes before the charge window we should program it (do not set above 30 if you are using Agile or similar)
@@ -167,7 +167,7 @@ If you have **inverter_hybrid** set to False then if **inverter_soc_reset** is s
 
 **set_reserve_enable** When True the reserve % will be reprogrammed during a charging window or discharging window to match the target SOC/discharge % in order
 to prevent discharge and then reset back to minimum % outside the window. Set the set_reserve_min to your minimum reserve % which is often 4%.
-The feature applies with **set_soc_enable** or **set_discharge_window** is True 
+The feature applies with **set_soc_enable** or **set_discharge_window** is True
 
 **set_reserve_min** Defines the reserve percentage to reset the reserve to when not in use, a value of 4 is the minimum and recommended to make use of the full battery
 

docs/developing.md

@@ -0,0 +1,98 @@
+# Developing on Predbat
+
+## Creating a fork
+
+Using GitHub, take a fork of Predbat - effectively, this creates
+a copy of the main repository, but in your personal space.
+There, you can create branches to develop on.
+
+## Pull requests
+
+Once you've completed your work on your branch, you can create a
+pull request (PR) to merge your work back in to the `main` branch
+of Predbat.
+
+This PR should describe the work you've done in a way that
+makes it easy for someone to review your work, and either
+add comments or approve it.
+
+## Editing the code
+
+There are at least a couple of ways of working on the code, outlined here.
+
+### Using GitHub Codespaces
+
+Especially if you don't need to have a running Home Assistant system
+to make the changes you're interested in (e.g. for documentation,
+quick fixes etc.) a really easy way to work on the code is using
+GitHub Codespaces.
+
+This gives you an easy way to spin up an environment with the right
+dependencies, and an IDE to work in (Visual Studio Code).
+
+From your fork, click on the Code button, and select the Codespaces tab.
+You can create multiple environments, or use a single environment and swap
+between branches in it.
+
+Also, you can choose between running the IDE in the browser, or having
+your local installation of VS Code connect to the environment that GitHub
+Codespaces has created for you. The local installation is better in some
+scenarios e.g. if you need to connect to a specific port, such as if you're
+working on the documentation.
+
+The Codespaces will be already set up for Python, along with various
+Python packages (as defined in `requirements.txt`). The environment
+is configured through the config in `.devcontainer/devcontainer.json`.
+
+### Developing locally within Home Assistant
+
+To be documented later.
+
+## Working on the documentation
+
+### The documentation build process
+
+The documentation for the site is built using `mkdocs`, which will
+already be installed if you're using a GitHub Codespaces environment.
+
+`mkdocs.yml` contains the config for defining the documentation site,
+and is built by `mkdocs` reading the Markdown files in the `docs/` folder,
+and creating HTML files from those files.
+
+The building of the documentation is triggered by a GitHub action,
+as defined in `.github/workflows/main.yml`.
+
+In short, after configuring the build environment, `mkdocs` builds the
+site, then pushes the HTML produced to the `gh-pages` branch,
+overwriting whatever was there previously.
+
+GitHub will then detect a new commit on the `gh-pages` branch,
+and that will trigger another action to run (as defined by GitHub).
+This action will take the HTML files on the `gh-pages` branch,
+and will make it available at [https://springfall2008.github.io/batpred/](https://springfall2008.github.io/batpred/).
+
+The documentation will be published as it is, with no further
+review process, so please ensure you check the documentation
+that will be built before merging it in.
+
+### Working locally on the documentation
+
+If you are making changes to the documentation, you can see
+a live updated version of the documentation as it will be
+built and deployed.
+
+To do this, run `mkdocs serve` - this will cause `mkdocs` to build the
+documentation site, and to temporarily publish it on port 8000 - it will
+show the link where you can access the documentation.
+
+Also, it will watch the `docs/` folder, and any time you change the
+files, it will rebuild the site, allowing you to see changes to
+the Markdown files in your browser within a few seconds.
+
+The site will continue being served until you press `CTRL-C` to
+end the `mkdocs serve` command.
+
+*Note, accessing the site published by `mkdocs serve` is not
+possible if you are using Codespaces to run VS Code in the browser,
+but it is possible if you're using it via VS Code running locally,
+due to the way in which ports on your environment are shared.*

docs/step-by-step-guide.md → docs/installation-summary.md

@@ -1,6 +1,6 @@
-# Step by step guide
+# Installation summary
 
-Note there is a step by step guide video, see the video guides section below for a link. 
+Note there are [step by step installation](video-guides.md#basic-installation) videos, see the [video guides](video-guides.md) section for those and other videos.
 
 Please see the sections below for how to achieve each step. This is just a checklist of things:
 
@@ -29,4 +29,3 @@ Please see the sections below for how to achieve each step. This is just a check
 Overview of the key configuration elements:
 
 ![image](https://github.com/springfall2008/batpred/assets/48591903/7c9350e0-2b6d-49aa-8f61-93d0547ae6d0)
-