From 9b4d6b3afe415dd8665ccd384a6e39a027dd31c1 Mon Sep 17 00:00:00 2001
From: Julianne Swinoga <julianneswinoga@gmail.com>
Date: Tue, 2 Jan 2024 21:40:44 -0500
Subject: [PATCH] PropertyTree documentation cleanup, change intersphinx python
 to point at 3.6

---
 docs/source/conf.py               |  3 ++-
 flightgear_python/fg_if.py        | 24 +++++++++++++++++++++++-
 flightgear_python/general_util.py |  4 ++++
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index cf371a2..cc622d2 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -19,7 +19,8 @@
 autosummary_generate = True
 
 intersphinx_mapping = {
-    'python': ('http://docs.python.org/3', None),
+    'python': ('https://docs.python.org/3.6', None),
+    'requests': ('https://requests.readthedocs.io/en/latest/', None),
 }
 
 templates_path = ['_templates']
diff --git a/flightgear_python/fg_if.py b/flightgear_python/fg_if.py
index c01d4c7..fe516d7 100755
--- a/flightgear_python/fg_if.py
+++ b/flightgear_python/fg_if.py
@@ -187,6 +187,10 @@ def __init__(self, gui_version: int):
 
 
 class PropertyTreeValue(NamedTuple):
+    """
+    Internal representation for working with values from the property tree
+    sphinx-no-autodoc
+    """
     absolute_path: str
     value_str: str
     type_str: str
@@ -216,6 +220,10 @@ def _auto_convert_fg_prop(value_str: str, type_str: str) -> Any:
 
     @staticmethod
     def check_and_normalize_prop_path(path: str) -> str:
+        """
+        Make sure the path is always absolute and strip trailing slashes
+        sphinx-no-autodoc
+        """
         if not path.startswith('/'):
             raise ValueError(f'Path must be absolute (start with /): {path}')
         path = path.rstrip('/') if path != "/" else path  # Strip trailing slash to keep things consistent
@@ -396,6 +404,10 @@ def set_prop(self, prop_str: str, value: Any):
         # We don't care about the response
 
     def get_values_and_dirs(self, path: str) -> Tuple[List[PropertyTreeValue], List[str]]:
+        """
+        Internal method to populate a shared property tree data structure
+        sphinx-no-autodoc
+        """
         resp_list = self._send_cmd_get_resp(f'ls {path}').split('\r\n')
         val_list: List[PropertyTreeValue] = []
         dir_list: List[str] = []
@@ -434,7 +446,13 @@ def __init__(self, host: str, tcp_port: int, timeout_s: float = 2.0):
         self.timeout_s = timeout_s
 
     def request_shim(self, method: str, url: str, *args, **kwargs) -> requests.Response:
-        # Shim layer over session.request so we can set default options and handle errors in a unified fashion
+        """
+        Shim layer over session.request so we can set default options and handle errors in a unified fashion
+        sphinx-no-autodoc
+
+        :param method: Directly copied from :meth:`requests.Session.request()`
+        :param url: Directly copied from :meth:`requests.Session.request()`
+        """
         try:
             return self.session.request(method, url, *args, timeout=self.timeout_s, **kwargs)
         except requests.exceptions.ConnectionError:
@@ -475,6 +493,10 @@ def set_prop(self, prop_str: str, value: Any):
         # We don't care about the response
 
     def get_values_and_dirs(self, path: str) -> Tuple[List[PropertyTreeValue], List[str]]:
+        """
+        Internal method to populate a shared property tree data structure
+        sphinx-no-autodoc
+        """
         resp_json = self.request_shim('GET', self.url + path).json()
         if resp_json['nChildren'] == 0:
             return [], []
diff --git a/flightgear_python/general_util.py b/flightgear_python/general_util.py
index b165036..8e26750 100644
--- a/flightgear_python/general_util.py
+++ b/flightgear_python/general_util.py
@@ -71,6 +71,10 @@ def strip_end(text: Union[str, ByteString], suffix: Union[str, ByteString]) -> U
 
 
 def deprecate_rename_wrapper(old_obj: object, old_fn: str, new_obj: object, new_fn: str):
+    """
+    Small wrapper function to soft-rename objects
+    sphinx-no-autodoc
+    """
     def new_fn_with_warning(*args, **kwargs):
         # Turn on warnings after the old name has been used
         warnings.simplefilter('default')