Improve Documentation for captcha (#680)

* Fix wording for CLI * Improve captcha documentation * Update captcha documentation * Improve documentation
bimmerconnected · Nov 24, 2024 · 81a1da6 · 81a1da6
1 parent 40ba148
commit 81a1da6
Show file tree

Hide file tree

Showing 5 changed files with 43 additions and 25 deletions.
diff --git a/README.rst b/README.rst
@@ -39,13 +39,14 @@ While this library is mainly written to be included in `Home Assistant <https://
 After installation, execute :code:`bimmerconnected` from command line for usage instruction
 or see the full `CLI documentation <http://bimmer-connected.readthedocs.io/en/stable/#cli>`_.
 
+.. warning::
+
+   Login to **north american** and **rest of world** accounts requires a captcha to be solved. See `Using Captchas <http://bimmer-connected.readthedocs.io/en/stable/captcha.html>`_ for more information.
+
 Please be aware that :code:`bimmer_connected` is an :code:`async` library when using it in Python code.
 The description of the :code:`modules` can be found in the `module documentation
 <http://bimmer-connected.readthedocs.io/en/stable/#module>`_.
 
-.. note::
-    Login to **north american** accounts requires a captcha to be solved. See `Captcha (North America) <http://bimmer-connected.readthedocs.io/en/stable/captcha.html>`_ for more information.
-
 Example in an :code:`asyncio` event loop
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ::
@@ -55,7 +56,8 @@ Example in an :code:`asyncio` event loop
     from bimmer_connected.api.regions import Regions
 
     async def main():
-        account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD)
+        # hcaptcha_token is only required for the first login, see the captcha documentation
+        account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD, hcaptcha_token="P1_eY...")
         await account.get_vehicles()
         vehicle = account.get_vehicle(VIN)
         print(vehicle.brand, vehicle.name, vehicle.vin)
@@ -75,8 +77,8 @@ Example in non-async code
     from bimmer_connected.account import MyBMWAccount
     from bimmer_connected.api.regions import Regions
 
-
-    account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD)
+    # hcaptcha_token is only required for the first login, see the captcha documentation
+    account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD, hcaptcha_token="P1_eY...")
     asyncio.run(account.get_vehicles())
     vehicle = account.get_vehicle(VIN)
     print(vehicle.brand, vehicle.name, vehicle.vin)

diff --git a/docs/source/captcha.rst b/docs/source/captcha.rst
@@ -3,35 +3,27 @@ Using Captchas
 
 The **first** login requires a captcha to be solved. Follow-up logins using refresh token do not require a captcha (if login data is persisted).
 
-.. note::
-   The captcha token is only valid for a short time and can only be used once.
+Getting a captcha token
+------------------------
 
 Depending on your region, you will need to solve a different captcha. Please select the appropriate region below.
 
 - `North America <captcha/north_america.html>`_
 - `Rest of World <captcha/rest_of_world.html>`_
 
-Using the Python API
----------------------
-
-When using the Python API, pass the token via the :code:`hcaptcha_token` argument when creating the account object.
-
 .. warning::
+   The captcha token is only valid for a short time and can only be used once.
 
-   Ensure to save the current :code:`MyBMWAccount` instance (or at least, the :code:`refresh_token` and :code:`gcid` attributes) to avoid having to solve the captcha again.
-
-::
 
-  account = MyBMWAccount(USERNAME, PASSWORD, REGION, hcaptcha_token=HCAPTCHA_TOKEN)
+Using Home Assistant
+--------------------
 
+When using the Home Assistant integration, simply paste the token into the config flow when configuring the account.
 
 Using the CLI
 -------------
-When using the CLI, pass the token via the :code:`--hcaptcha-token` argument (see `CLI documentation <cli.html#named-arguments>`_).
 
-.. warning::
-
-   Please make sure to use the :code:`--oauth-store` (used by default) to avoid having to solve the captcha again.
+When using the CLI, pass the token via the :code:`--captcha-token` argument (see `CLI documentation <cli.html#named-arguments>`_).
 
 ::
 
@@ -43,4 +35,26 @@ After a successful login, the :code:`--captcha-token` parameter can be omitted (
 
   bimmerconnected status USERNAME PASSWORD REGION
 
+.. note::
+
+   Please make sure to use the :code:`--oauth-store` (used by default) to avoid having to solve the captcha again.
+
+Using the Python API
+---------------------
+
+When using the Python API, pass the token via the :code:`hcaptcha_token` argument when creating the account object.
+
+::
+
+  account = MyBMWAccount(USERNAME, PASSWORD, REGION, hcaptcha_token=HCAPTCHA_TOKEN)
+
+.. warning::
+
+   Ensure to keep the current :code:`MyBMWAccount` instance in memory to avoid having to solve the captcha again.
+
+For storing the data across restarts, an example implementation can be found in
+`bimmerconnected.main() <https://github.com/bimmerconnected/bimmer_connected/blob/40ba148579da6b45268ea8ed9eb252cbafbe9042/bimmer_connected/cli.py#L328>`_
+(with :code:`args.oauth_store` being a :code:`pathlib.Path()` object).
 
+If you are running this script inside another system (e.g. demoticz), you can also store and read the information using their native tools 
+- it does not have to be a JSON file, as long as the data is stored and read correctly.
diff --git a/docs/source/captcha/north_america.rst b/docs/source/captcha/north_america.rst
@@ -1,7 +1,7 @@
 Captcha (North America)
 =======================
 
-Please see :doc:`../captcha` for general information on using captchas.
+Please confirm that you are a human and submit the form. See :doc:`../captcha` for more information.
 
 .. raw:: html
    :file: north_america_form.html
diff --git a/docs/source/captcha/rest_of_world.rst b/docs/source/captcha/rest_of_world.rst
@@ -1,7 +1,7 @@
 Captcha (Rest of World)
 =======================
 
-Please see :doc:`../captcha` for general information on using captchas.
+Please confirm that you are a human and submit the form. See :doc:`../captcha` for more information.
 
 .. raw:: html
    :file: rest_of_world_form.html
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,3 +1,5 @@
+import datetime
+
 # Configuration file for the Sphinx documentation builder.
 #
 # This file does only contain a selection of the most common options. For a
@@ -17,8 +19,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'bimmer_connected'
-copyright = '2018-2020, m1n3rva, gerard33'
-author = 'rikroe'
+copyright = f'2018-{datetime.datetime.now().year}, m1n3rva, gerard33, rikroe'
+author = 'm1n3rva, gerard33, rikroe'
 
 # The short X.Y version
 # version = const.__version__