Documentation genertation improvements

paveldn · Sep 13, 2024 · 7e0ad6b · 7e0ad6b
1 parent 39a017a
commit 7e0ad6b
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 18 deletions.
diff --git a/README.rst b/README.rst
@@ -2,6 +2,8 @@
    Please, don't change. In case you need to make corrections or changes change
    source documentation in ./doc folder or script.
 
+.. Generated from see_also.rst
+
 .. Generated from esphome-docs/climate/haier.rst
 
 Haier Climate
@@ -567,19 +569,24 @@ flash_4M.bin**
 
 After this, you can flash firmware using ESPHome tools (dashboard,
 website, esphome command, etc)
-.. Generated from additional_information.rst
 
-Additional information
-======================
+See Also
+========
 
 - `FAQ <./docs/faq.rst>`_
 - `HaierProtocol <https://github.com/paveldn/HaierProtocol>`_
 - `Haier smart modules <./docs/haier_modules.rst>`_
 - `Haier protocol overview <./docs/protocol_overview.rst>`_
 - `Example of climate configuration for smartair2 protocol <./docs/smartair2_example.rst>`_
 - `Example of climate configuration for hOn protocol <./docs/hon_example.rst>`_
+- `Esptool.py Documentation <https://docs.espressif.com/projects/esptool/en/latest/esp32/>`_
+- `Sniffing serial communication <./docs/sniffing_serial_communication.rst>`_
 - `ESPHome Haier Climate <https://esphome.io/components/climate/haier.html>`_
 - `ESPHome Haier Climate Sensors <https://esphome.io/components/sensor/haier.html>`_
 - `ESPHome Haier Climate Binary Sensors <https://esphome.io/components/binary_sensor/haier.html>`_
-- `Esptool.py Documentation <https://docs.espressif.com/projects/esptool/en/latest/esp32/>`_
-- `Sniffing serial communication <./docs/sniffing_serial_communication.rst>`_
+- `ESPHome Haier Climate Text Sensors <https://esphome.io/components/text_sensor/haier.html>`_
+- `ESPHome Haier Climate Buttons <https://esphome.io/components/button/haier.html>`_
+- `ESPHome Haier Climate Switches <https://esphome.io/components/switch/haier.html>`_
+- `Climate Component <https://esphome.io/components/climate/>`_
+- `API Reference <https://esphome.io/api/haier__base_8h.html>`_
+- `Sensor Filters <https://esphome.io/components/sensor/#sensor-filters>`_
diff --git a/docs/esphome-docs/climate/haier.rst b/docs/esphome-docs/climate/haier.rst
@@ -53,7 +53,7 @@ Newer Haier models using a module called ESP32-for-Haier. It is an ESP32 single-
 
 Also, you can use any other ESP32, ESP8266, or an RPI pico W board. In this case, you will need to cut the original wire or make a connector yourself (the board has a JST SM04B-GHS-TB connector)
 
-This component requires a :ref:`uart` to be setup.
+This component requires a :ref:`UART bus <uart>` to be setup.
 
 .. code-block:: yaml
 
@@ -343,5 +343,5 @@ See Also
 - :doc:`Haier Climate Buttons </components/button/haier>`
 - :doc:`Haier Climate Switches </components/switch/haier>`
 - :doc:`/components/climate/index`
-- :apiref:`haier/climate/haier.h`
+- :apiref:`haier/climate/haier_base.h`
 - :ghedit:`Edit`
diff --git a/docs/script/make_doc.py b/docs/script/make_doc.py
@@ -3,39 +3,51 @@
 import sys
 
 doc_file_path = [
+    "see_also.rst",
     "/".join(["esphome-docs", "climate", "haier.rst"]),
     "/".join(["esphome-docs", "sensor", "haier.rst"]),
     "/".join(["esphome-docs", "binary_sensor", "haier.rst"]),
     "/".join(["esphome-docs", "text_sensor", "haier.rst"]),
     "/".join(["esphome-docs", "button", "haier.rst"]),
     "/".join(["esphome-docs", "switch", "haier.rst"]),
     "esp32_backup.rst",
-    "additional_information.rst",
 ]
 
 def process_esphome_refs(line, l_num):
     esphome_refs = [
-        (":ref:`uart`", "`UART Bus <https://esphome.io/components/uart#uart>`_"),
         (":ref:`config-id`", "`ID <https://esphome.io/guides/configuration-types.html#config-id>`_"),
         (":ref:`config-time`", "`Time <https://esphome.io/guides/configuration-types.html#config-time>`_"),
         (":ref:`Automation <automation>`", "`Automation <https://esphome.io/guides/automations#automation>`_"),
+        (":ref:`lambdas <config-lambda>`", "`lambdas <https://esphome.io/guides/automations#config-lambda>`_"),
         (":ref:`haier-on_alarm_start`", "`on_alarm_start Trigger`_"),
         (":ref:`haier-on_alarm_end`", "`on_alarm_end Trigger`_"),
         (":ref:`haier-on_status_message`", "`on_status_message Trigger`_"),
+        (":ref:`UART bus <uart>`", "`UART Bus <https://esphome.io/components/uart#uart>`_"),
         (":ref:`Climate <config-climate>`", "`Climate <https://esphome.io/components/climate/index.html#config-climate>`_"),
-        (":ref:`lambdas <config-lambda>`", "`lambdas <https://esphome.io/guides/automations#config-lambda>`_"),
         (":ref:`Sensor <config-sensor>`", "`Sensor <https://esphome.io/components/sensor/index.html#config-sensor>`_"),
         (":ref:`Binary Sensor <config-binary_sensor>`", "`Binary Sensor <https://esphome.io/components/binary_sensor/index.html#base-binary-sensor-configuration>`_"),
         (":ref:`Text Sensor <config-text_sensor>`", "`Text Sensor <https://esphome.io/components/text_sensor/index.html#base-text-sensor-configuration>`_"),
         (":ref:`Button <config-button>`", "`Button <https://esphome.io/components/button/index.html#base-button-configuration>`_"),
         (":ref:`Switch <config-switch>`", "`Switch <https://esphome.io/components/switch/index.html#base-switch-configuration>`_"),
         (":ref:`Select <config-select>`", "`Select <https://esphome.io/components/select/index.html#base-select-configuration>`_"),
+        (":ghedit:`Edit`", ""),
+        (":doc:`/components/climate/index`", "`Climate Component <https://esphome.io/components/climate/>`_"),
+        (":doc:`Haier Climate </components/climate/haier>`", "`ESPHome Haier Climate <https://esphome.io/components/climate/haier.html>`_"),
+        (":apiref:`haier/climate/haier_base.h`", "`API Reference <https://esphome.io/api/haier__base_8h.html>`_"),
+        (":ref:`sensor-filters`", "`Sensor Filters <https://esphome.io/components/sensor/#sensor-filters>`_"),
+        (":doc:`Haier Climate Sensors </components/sensor/haier>`", "`ESPHome Haier Climate Sensors <https://esphome.io/components/sensor/haier.html>`_"),
+        (":doc:`Haier Climate Binary Sensors </components/binary_sensor/haier>`", "`ESPHome Haier Climate Binary Sensors <https://esphome.io/components/binary_sensor/haier.html>`_"),
+        (":doc:`Haier Climate Text Sensors </components/text_sensor/haier>`", "`ESPHome Haier Climate Text Sensors <https://esphome.io/components/text_sensor/haier.html>`_"),
+        (":doc:`Haier Climate Buttons </components/button/haier>`", "`ESPHome Haier Climate Buttons <https://esphome.io/components/button/haier.html>`_"),
+        (":doc:`Haier Climate Switches </components/switch/haier>`", "`ESPHome Haier Climate Switches <https://esphome.io/components/switch/haier.html>`_"),
     ]
     res = line
     for o, r in esphome_refs:
         res = res.replace(o, r)
     if res.find(":ref:") != -1:
         print(f"\tWarning: ref found, line #{l_num}")
+    if res.find(":doc:") != -1:
+        print(f"\tWarning: doc found, line #{l_num}")
     return res
 
 def process_figure(section, output_file, pth):
@@ -70,6 +82,17 @@ def process_section(section, output_file, pth):
     else:
         output_file.writelines(section)
 
+def process_see_also(see_also_lines, output_file):
+    print("Processing See Also section")
+    output_file.write("\nSee Also\n")
+    output_file.write("========\n\n")
+    l_counter = 0
+    for l in see_also_lines:
+        if l.find("<https://github.com/paveldn/haier-esphome>") == -1:
+            l_counter += 1
+            output_file.write(f"- {l}\n")
+    print(f"\tProcessed {l_counter} line(s)")
+
 document_header = [
     ".. This file is automatically generated by ./docs/script/make_doc.py Python script.\n",
     "   Please, don't change. In case you need to make corrections or changes change\n",
@@ -82,6 +105,7 @@ def process_section(section, output_file, pth):
     output_file_name = sys.argv[1]
 output_file = open(output_file_name, "w")
 output_file.writelines(document_header)
+see_also_lines = []
 for in_f in doc_file_path:
     print(f"Processing: {in_f}")
     output_file.write(f".. Generated from {in_f}\n\n")
@@ -90,12 +114,20 @@ def process_section(section, output_file, pth):
     lines = input_file.readlines()
     is_seo = False
     is_section = False
+    is_in_see_also = False
     section = []
     l_counter = 0
     for line in lines:
         l_counter += 1
         if line == "See Also\n":
-            break
+            is_in_see_also = True
+            continue
+        if is_in_see_also:
+            if line.startswith('- '):
+                processed_line = process_esphome_refs(line[2:].rstrip(), l_counter)
+                if processed_line and (processed_line not in see_also_lines):
+                    see_also_lines.append(processed_line)
+            continue
         if is_section:
             if (line in ['\n', '\r\n']) or line.startswith("  "):
                 section.append(line)
@@ -116,4 +148,5 @@ def process_section(section, output_file, pth):
             continue
         l = process_esphome_refs(line, l_counter)
         output_file.write(l)
-    print(f"\tProcessed {l_counter} line(s)")
+    print(f"\tProcessed {l_counter} line(s)")
+process_see_also(see_also_lines, output_file)
diff --git a/docs/additional_information.rst → docs/see_also.rst b/docs/additional_information.rst → docs/see_also.rst
@@ -1,14 +1,12 @@
-Additional information
-======================
+See Also
+--------
 
 - `FAQ <./docs/faq.rst>`_
 - `HaierProtocol <https://github.com/paveldn/HaierProtocol>`_
 - `Haier smart modules <./docs/haier_modules.rst>`_
 - `Haier protocol overview <./docs/protocol_overview.rst>`_
 - `Example of climate configuration for smartair2 protocol <./docs/smartair2_example.rst>`_
 - `Example of climate configuration for hOn protocol <./docs/hon_example.rst>`_
-- `ESPHome Haier Climate <https://esphome.io/components/climate/haier.html>`_
-- `ESPHome Haier Climate Sensors <https://esphome.io/components/sensor/haier.html>`_
-- `ESPHome Haier Climate Binary Sensors <https://esphome.io/components/binary_sensor/haier.html>`_
 - `Esptool.py Documentation <https://docs.espressif.com/projects/esptool/en/latest/esp32/>`_
-- `Sniffing serial communication <./docs/sniffing_serial_communication.rst>`_
+- `Sniffing serial communication <./docs/sniffing_serial_communication.rst>`_
+- :doc:`Haier Climate </components/climate/haier>`