Skip to content

Commit

Permalink
Fixing sphinx errors
Browse files Browse the repository at this point in the history
  • Loading branch information
@tcamise-gpsw
tcamise-gpsw committed Jul 19, 2024
1 parent f936a52 commit ddc0096
Show file tree
Hide file tree
Showing 19 changed files with 290 additions and 316 deletions.
6 changes: 6 additions & 0 deletions demos/python/sdk_wireless_camera_control/docs/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,8 @@ These should not be imported directly and instead should be accessed using the r
Base Types
----------

.. automodule:: open_gopro.types

GoPro Enum
^^^^^^^^^^

Expand Down Expand Up @@ -173,6 +175,8 @@ These are the various models that are returned in responses, used in commands, e
from open_gopro.models import ***
.. autopydantic_model:: open_gopro.models.media_list.MediaPath

.. autopydantic_model:: open_gopro.models.media_list.MediaMetadata

.. autopydantic_model:: open_gopro.models.media_list.PhotoMetadata
Expand Down Expand Up @@ -221,6 +225,8 @@ Exceptions
Common Interface
================

.. automodule:: open_gopro.parser_interface

.. autoclass:: open_gopro.gopro_base.GoProBase

.. autoclass:: open_gopro.communicator_interface.GoProBle
Expand Down
80 changes: 54 additions & 26 deletions demos/python/sdk_wireless_camera_control/docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@

from open_gopro import WirelessGoPro

from sphinx.ext.intersphinx import missing_reference

import open_gopro
import open_gopro.models

gopro = WirelessGoPro(enable_wifi=False)

project = "Open GoPro Python SDK"
Expand All @@ -23,8 +28,8 @@
"sphinx.ext.autosectionlabel",
"sphinx.ext.graphviz",
"sphinx.ext.inheritance_diagram",
# "sphinxemoji.sphinxemoji", # https://github.com/sphinx-contrib/emojicodes/issues/42
"sphinxcontrib.autodoc_pydantic",
"sphinx.ext.intersphinx",
]
html_theme = "sphinx_rtd_theme"
html_context = {
Expand All @@ -39,6 +44,9 @@
# https://autodoc-pydantic.readthedocs.io/en/stable/users/installation.html#configuration
autodoc_pydantic_model_show_json = True
autodoc_pydantic_settings_show_json = False
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
}

# The version info for the project you're documenting, acts as replacement
# for |version| and |release|, also used in various other places throughout
Expand All @@ -51,52 +59,72 @@

nitpicky = True

TYPE_ALIASES = {
"CameraState": "open_gopro.types.CameraState",
"UpdateCb": "open_gopro.types.UpdateCb",
"UpdateType": "open_gopro.types.UpdateType",
"JsonDict": "open_gopro.JsonDict",
"ResponseType": "open_gopro.types.ResponseType",
"Protobuf": "open_gopro.types.Protobuf",
"IdType": "open_gopro.types.IdType",
}

# This is very broken.
# https://github.com/sphinx-doc/sphinx/issues/10455
# https://github.com/sphinx-doc/sphinx/issues/10785
# autodoc_type_aliases = {
# "IdType": "open_gopro.interface.IdType",
# "CommunicatorType": "open_gopro.interface.CommunicatorType",
# "ParserType": "open_gopro.interface.ParserType",
# "DisconnectHandlerType": "open_gopro.ble.controller.DisconnectHandlerType",
# "NotiHandlerType": "open_gopro.ble.controller.NotiHandlerType",
# "ValueType": "open_gopro.api.builders.ValueType",
# "BleDevice": "open_gopro.ble.controller.BleDevice",
# "BleHandle": "open_gopro.ble.controller.BleHandle",
# "CmdType": "open_gopro.constants.CmdType",
# "ResponseType": "open_gopro.constants.ResponseType",
# "CameraState": "open_gopro.types.CameraState",
# "Path": "pathlib.Path",
# }

nitpick_ignore = [
("py:class", "T"),
("py:class", "T_co"),
("py:class", "ExceptionHandler"),
("py:class", "datetime.datetime"),
("py:class", "open_gopro.models.parsers.Parser"),
("py:class", "abc.ABC"),
("py:class", "collections.abc.Iterable"),
]
nitpick_ignore_regex = [
(r"py:class", r".*proto\..+"), # TODO how should / can we handle protobuf documenting?
(r"py:class", r".*_pb2\..+"),
(r"py:class", r".+Type"),
(r"py:obj", r".+Type"),
(r"py:class", r".*Path"),
(r"py:class", r".*InitVar"),
(r"py:class", r".*UpdateCb"),
(r"py:class", r".*JsonDict"),
(r"py:class", r".*BleDevice"),
(r"py:class", r".*BleHandle"),
(r"py:class", r".*Parser"),
(r"py:class", r".*Builder"),
(r".*", r".*construct.*"),
(r".*", r".*response.T*"),
# Generic Types that are pointless to document
(r"py:class", r".*\.T"),
(r"py:class", r".*\.T_co"),
(r"py:class", r".*BleHandle"),
(r"py:class", r".*BleDevice"),
(r"py:class", r".*CommunicatorType"),
(r"py:class", r".*NotiHandlerType"),
(r"py:obj", r".*CommunicatorType"),
(r"py:obj", r".*MessageType"),
]


# This is the expected signature of the handler for this event, cf doc
def autodoc_skip_member_handler(app, what, name, *_):
for skip in ("internal", "deprecated"):
if skip in name.lower():
return name


def resolve_type_aliases(app, env, node, contnode):
"""Resolve :class: references to our type aliases as :attr: instead."""
try:
if node["refdomain"] == "py" and (target := TYPE_ALIASES.get(node["reftarget"])):
print(f"updating {node['reftarget']}")
return app.env.get_domain("py").resolve_any_xref(
env,
node["refdoc"],
app.builder,
target,
node,
contnode,
)[
0
][1]
except IndexError:
print("uhoh")
return None


def setup(app):
app.connect("autodoc-skip-member", autodoc_skip_member_handler)
app.connect("missing-reference", resolve_type_aliases)
28 changes: 14 additions & 14 deletions demos/python/sdk_wireless_camera_control/open_gopro/api/ble_commands.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
this,
)

from open_gopro import proto, types
from open_gopro import proto
from open_gopro.api.builders import BleAsyncResponse
from open_gopro.api.builders import BleSettingFacade as BleSetting
from open_gopro.api.builders import BleStatusFacade as BleStatus
Expand Down Expand Up @@ -56,7 +56,7 @@
from open_gopro.models import CameraInfo, TzDstDateTime
from open_gopro.models.response import GlobalParsers, GoProResp
from open_gopro.parser_interface import Parser
from open_gopro.types import CameraState
from open_gopro.types import CameraState, UpdateCb

from . import params as Params

Expand Down Expand Up @@ -344,11 +344,11 @@ async def get_wifi_password(self) -> GoProResp[str]:
update_set=StatusId,
action=RegisterUnregisterAll.Action.REGISTER,
)
async def register_for_all_statuses(self, callback: types.UpdateCb) -> GoProResp[None]:
async def register_for_all_statuses(self, callback: UpdateCb) -> GoProResp[None]:
"""Register push notifications for all statuses
Args:
callback (types.UpdateCb): callback to be notified with
callback (UpdateCb): callback to be notified with
Returns:
GoProResp[None]: command status and current value of all statuses
Expand All @@ -360,11 +360,11 @@ async def register_for_all_statuses(self, callback: types.UpdateCb) -> GoProResp
update_set=StatusId,
action=RegisterUnregisterAll.Action.UNREGISTER,
)
async def unregister_for_all_statuses(self, callback: types.UpdateCb) -> GoProResp[None]:
async def unregister_for_all_statuses(self, callback: UpdateCb) -> GoProResp[None]:
"""Unregister push notifications for all statuses
Args:
callback (types.UpdateCb): callback to be notified with
callback (UpdateCb): callback to be notified with
Returns:
GoProResp[None]: command status
Expand All @@ -376,11 +376,11 @@ async def unregister_for_all_statuses(self, callback: types.UpdateCb) -> GoProRe
update_set=SettingId,
action=RegisterUnregisterAll.Action.REGISTER,
)
async def register_for_all_settings(self, callback: types.UpdateCb) -> GoProResp[None]:
async def register_for_all_settings(self, callback: UpdateCb) -> GoProResp[None]:
"""Register push notifications for all settings
Args:
callback (types.UpdateCb): callback to be notified with
callback (UpdateCb): callback to be notified with
Returns:
GoProResp[None]: command status and current value of all settings
Expand All @@ -392,11 +392,11 @@ async def register_for_all_settings(self, callback: types.UpdateCb) -> GoProResp
update_set=SettingId,
action=RegisterUnregisterAll.Action.UNREGISTER,
)
async def unregister_for_all_settings(self, callback: types.UpdateCb) -> GoProResp[None]:
async def unregister_for_all_settings(self, callback: UpdateCb) -> GoProResp[None]:
"""Unregister push notifications for all settings
Args:
callback (types.UpdateCb): callback to be notified with
callback (UpdateCb): callback to be notified with
Returns:
GoProResp[None]: command status
Expand All @@ -408,11 +408,11 @@ async def unregister_for_all_settings(self, callback: types.UpdateCb) -> GoProRe
update_set=SettingId,
action=RegisterUnregisterAll.Action.REGISTER,
)
async def register_for_all_capabilities(self, callback: types.UpdateCb) -> GoProResp[None]:
async def register_for_all_capabilities(self, callback: UpdateCb) -> GoProResp[None]:
"""Register push notifications for all capabilities
Args:
callback (types.UpdateCb): callback to be notified with
callback (UpdateCb): callback to be notified with
Returns:
GoProResp[None]: command status and current value of all capabilities
Expand All @@ -424,11 +424,11 @@ async def register_for_all_capabilities(self, callback: types.UpdateCb) -> GoPro
update_set=SettingId,
action=RegisterUnregisterAll.Action.UNREGISTER,
)
async def unregister_for_all_capabilities(self, callback: types.UpdateCb) -> GoProResp[None]:
async def unregister_for_all_capabilities(self, callback: UpdateCb) -> GoProResp[None]:
"""Unregister push notifications for all capabilities
Args:
callback (types.UpdateCb): callback to be notified with
callback (UpdateCb): callback to be notified with
Returns:
GoProResp[None]: command status
Expand Down
Loading

0 comments on commit ddc0096

Please sign in to comment.