Merge pull request #41 from bernhardkaindl/doctree-add-settings-helpers

Thank you

Author: igo95862

docs/index.rst

@@ -12,7 +12,7 @@ of `NetworkManager <https://wiki.gnome.org/Projects/NetworkManager>`_.
     examples
     device_interfaces
     other_interfaces
-    options
+    profile_settings
     enums
     exceptions
 

docs/options.rst docs/profile_settings.rstdocs/options.rst renamed to docs/profile_settings.rst

@@ -1,5 +1,6 @@
-Network Manager settings
-========================
+Connection Profile Settings Helpers
+===================================
+
 
 .. autoclass:: sdbus_async.networkmanager.settings.ConnectionSettings
     :members:

sdbus_async/networkmanager/settings/match.py

@@ -16,20 +16,21 @@ class MatchSettings(NetworkManagerSettingsMixin):
         default=None,
     )
     """A list of driver names to match. Each element is a shell wildcard pattern.
-    See NMSettingMatch:interface-name for how special characters '|', '&', '!' and
-    '\\' are used for optional and mandatory matches and inverting the pattern."""
+    See NMSettingMatch:interface-name for how special characters '\|', '&', '!'
+    and '\\' are used for optional and mandatory matches and inverting the
+    pattern."""
     interface_name: Optional[List[str]] = field(
         metadata={'dbus_name': 'interface-name', 'dbus_type': 'as'},
         default=None,
     )
     """A list of interface names to match. Each element is a shell wildcard
-    pattern. An element can be prefixed with a pipe symbol (|) or an ampersand
+    pattern. An element can be prefixed with a pipe symbol (\|) or an ampersand
     (&). The former means that the element is optional and the latter means that
     it is mandatory. If there are any optional elements, than the match evaluates
     to true if at least one of the optional element matches (logical OR). If there
     are any mandatory elements, then they all must match (logical AND). By
     default, an element is optional. This means that an element "foo" behaves the
-    same as "|foo". An element can also be inverted with exclamation mark (!)
+    same as "\|foo". An element can also be inverted with exclamation mark (!)
     between the pipe symbol (or the ampersand) and before the pattern. Note that
     "!foo" is a shortcut for the mandatory match "&!foo". Finally, a backslash can
     be used at the beginning of the element (after the optional special
@@ -46,7 +47,7 @@ class MatchSettings(NetworkManagerSettingsMixin):
     command line is searched for the word appearing as is, or as left hand side of
     an assignment. In the latter case, the exact assignment is looked for with
     right and left hand side matching. Wildcard patterns are not supported. See
-    NMSettingMatch:interface-name for how special characters '|', '&', '!' and
+    NMSettingMatch:interface-name for how special characters '\|', '&', '!' and
     '\\' are used for optional and mandatory matches and inverting the match."""
     path: Optional[List[str]] = field(
         metadata={'dbus_name': 'path', 'dbus_type': 'as'},
@@ -58,8 +59,8 @@ class MatchSettings(NetworkManagerSettingsMixin):
     specific identifier. For PCI devices the path has the form
     "pci-$domain:$bus:$device.$function", where each variable is an hexadecimal
     value; for example "pci-0000:0a:00.0". The path of a device can be obtained
-    with "udevadm info /sys/class/net/$dev | grep ID_PATH=" or by looking at the
+    with "udevadm info /sys/class/net/$dev \| grep ID_PATH=" or by looking at the
     "path" property exported by NetworkManager ("nmcli -f general.path device show
     $dev"). Each element of the list is a shell wildcard pattern. See
-    NMSettingMatch:interface-name for how special characters '|', '&', '!' and
+    NMSettingMatch:interface-name for how special characters '\|', '&', '!' and
     '\\' are used for optional and mandatory matches and inverting the pattern."""

tools/generate-settings-dataclasses.py

@@ -10,15 +10,6 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional, OrderedDict, Tuple
 
-
-def dbg(msg: Any) -> None:
-    print(f"{msg}")
-
-
-def write(msg: Any) -> None:
-    print(f"{msg}")
-
-
 dbus_type_name_map = {
     "b": "bool",
     "s": "str",
@@ -219,21 +210,22 @@ def find_first_not_none(itr: List[Any]) -> Optional[Any]:
 
 # Generate docs/options.rst, see:
 # https://github.com/python-sdbus/python-sdbus-networkmanager/pull/39#issuecomment-1186522147
-def open_options_rst() -> io.TextIOWrapper:
-    options_rst = open("docs/options.rst", "w")
-    options_rst.write("Network Manager settings\n========================\n")
-    return options_rst
+def open_profile_settings_rst() -> io.TextIOWrapper:
+    profile_settings_rst = open("docs/profile_settings.rst", "w")
+    profile_settings_rst.write("Connection Profile Settings Helpers\n")
+    profile_settings_rst.write("===================================\n\n")
+    return profile_settings_rst
 
 
-def append_sphinx_autoclass(options_rst: io.TextIOWrapper, classname: str) -> None:
+def append_sphinx_autoclass(profile_settings: io.TextIOWrapper, classname: str) -> None:
     classpath = f"sdbus_async.networkmanager.settings.{classname}"
-    options_rst.write(f"\n.. autoclass:: {classpath}\n    :members:\n")
+    profile_settings.write(f"\n.. autoclass:: {classpath}\n    :members:\n")
 
 
 # The code quality of this function is poor(Sourcery says 5%), needs refactoring,
 # also see the rework in tools/generate-settings-dataclasses-jinja.py
 def main(settings_xml_path: Path) -> None:
-    options_rst = open_options_rst()
+    profile_settings_rst = open_profile_settings_rst()
     gl_input_files = [settings_xml_path]
 
     xml_roots = [ElementTree.parse(f).getroot() for f in gl_input_files]
@@ -315,7 +307,7 @@ def main(settings_xml_path: Path) -> None:
             p.write("    )\n")
         f.write("@dataclass\n")
         f.write(f"class {classname}(NetworkManagerSettingsMixin):\n")
-        append_sphinx_autoclass(options_rst, classname)
+        append_sphinx_autoclass(profile_settings_rst, classname)
 
         # generate the docstring of the new settings_class
         desc = node_get_attr(settings, "description")
@@ -390,13 +382,16 @@ def main(settings_xml_path: Path) -> None:
                 # developers when they lookup the attribute declaration:
                 generate_descriptions_for_attributes = True
                 if generate_descriptions_for_attributes:
-                    desc = node_get_attr(properties_attrs, "description")
+                    attr_description = node_get_attr(properties_attrs, "description")
+                    # Fix warning from sphinx: WARNING:
+                    # Inline substitution_reference start-string without end-string
+                    attr_docstring = attr_description.replace("|", "\|")
                     wrapper = textwrap.TextWrapper(
                         width=82,
                         initial_indent="    ",
                         subsequent_indent="    ",
                     )
-                    lines = wrapper.wrap(text=f'"""{desc}"""')
+                    lines = wrapper.wrap(text=f'"""{attr_docstring}"""')
                     if len(lines) == 1:
                         print(lines[0] + '"""')
                     else: