small docs update, still many work to do remain (#88)

Nothing fixed, nothing important added, just some additional
documentation with the help of sphinx.

Signed-off-by: Alexander Piskun <[email protected]>

Author: bigcat88

docs/conf.py

@@ -21,12 +21,17 @@
     "sphinx_inline_tabs",
     "sphinx_issues",
     "sphinx_rtd_theme",
+    "sphinxcontrib.autodoc_pydantic",
 ]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    # "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
+    # "redis": ("https://redis-py.readthedocs.io/en/stable/", None),
 }
 
+autodoc_pydantic_model_show_json = False
+
 # General information about the project.
 project = "NcPyApi"
 copyright = str(now.year) + " Nextcloud GmbH"  # noqa
@@ -48,7 +53,7 @@
     "display_version": True,
 }
 
-# If true, `todos` produce output, else they produce nothing.
+# If true, `todos` produce output. Else they produce nothing.
 todo_include_todos = False
 
 # The name of the Pygments (syntax highlighting) style to use.

docs/reference/ExApp.rst

@@ -11,3 +11,23 @@ Constants
 
 .. autoclass:: LogLvl
     :members:
+
+User Interface(UI)
+------------------
+
+UI methods should be accessed with the help of :class:`~nc_py_api.nextcloud.NextcloudApp`
+
+.. code-block:: python
+
+    # this is an example, in most cases you will get `NextcloudApp` class instance as input param.
+    nc = NextcloudApp()
+    nc.ui.files_dropdown_menu.register(...)
+
+.. autoclass:: nc_py_api.ex_app.ui.ui.UiApi
+    :members:
+
+.. automodule:: nc_py_api.ex_app.ui.files
+    :members:
+
+.. autoclass:: nc_py_api.ex_app.ui.files._UiFilesActionsAPI
+    :members:

docs/reference/Session.rst

@@ -15,7 +15,11 @@ Session Structures
 Internal
 ^^^^^^^^
 
-Currently Session API is private, and not exposed.
+.. note:: The Session API is currently private and subject to change without deprecation.
 
 .. autoclass:: NcSessionBasic
     :members:
+
+.. autoclass:: NcSessionApp
+    :members:
+    :inherited-members:

nc_py_api/ex_app/defs.py

@@ -19,7 +19,7 @@ class LogLvl(enum.IntEnum):
 
 
 class ApiScope(enum.IntEnum):
-    """Default API scopes."""
+    """Default API scopes. Should be used as a parameter to the :py:meth:`~.NextcloudApp.scope_allowed` method."""
 
     SYSTEM = 2
     """Allows access to the System APIs."""

nc_py_api/ex_app/ui/files.py

@@ -16,23 +16,33 @@ class UiActionFileInfo(BaseModel):
     """File Information Nextcloud sends to the External Application."""
 
     fileId: int
+    """FileID without Nextcloud instance ID"""
     name: str
+    """Name of the file/directory"""
     directory: str
+    """Directory relative to the user's home directory"""
     etag: str
     mime: str
     fileType: str
+    """**file** or **dir**"""
     size: int
+    """size of file/directory"""
     favorite: str
+    """**true** or **false**"""
     permissions: int
+    """Combination of :py:class:`~nc_py_api.files.FilePermissions` values"""
     mtime: int
+    """Last modified time"""
     userId: str
+    """The ID of the user performing the action."""
     shared: str
+    """**true** or **false**"""
 
     def to_fs_node(self) -> FsNode:
         """Returns created ``FsNode`` from the file info given.
 
-        .. note:: :py:class:FsNode.file_id in this case is ``without`` **instance_id**
-            and equal to :py:class:FsNode.info.fileid.
+        .. note:: :py:attr:`~nc_py_api.files.FsNode.file_id` in this case is ``without`` **instance_id**
+            and equal to :py:attr:`~nc_py_api.files.FsNodeInfo.fileid`.
         """
         user_path = os.path.join(self.directory, self.name).rstrip("/")
         is_dir = bool(self.fileType.lower() == "dir")
@@ -68,12 +78,15 @@ class UiFileActionHandlerInfo(BaseModel):
     """Action information Nextcloud sends to the External Application."""
 
     actionName: str
+    """Name of the action, useful when App registers multiple actions for one handler."""
     actionHandler: str
+    """Callback url, which was called with this information."""
     actionFile: UiActionFileInfo
+    """Information about the file on which the action run."""
 
 
 class _UiFilesActionsAPI:
-    """API for the drop-down menu in Nextcloud ``Files`` app."""
+    """API for the drop-down menu in Nextcloud **Files app**."""
 
     def __init__(self, session: NcSessionApp):
         self._session = session

nc_py_api/ex_app/ui/ui.py

@@ -11,6 +11,7 @@ class UiApi:
     """Class that encapsulates all UI functionality."""
 
     files_dropdown_menu: _UiFilesActionsAPI
+    """File dropdown menu API."""
 
     def __init__(self, session: NcSessionApp):
         self.files_dropdown_menu = _UiFilesActionsAPI(session)

nc_py_api/nextcloud.py

@@ -107,6 +107,7 @@ class NextcloudApp(_NextcloudBasic):
     appconfig_ex: AppConfigExAPI
     """Nextcloud App Preferences API for ExApps"""
     ui: UiApi
+    """Nextcloud UI API for ExApps"""
     preferences_ex: PreferencesExAPI
     """Nextcloud User Preferences API for ExApps"""
 
@@ -142,7 +143,7 @@ def users_list(self) -> list[str]:
     def scope_allowed(self, scope: ApiScope) -> bool:
         """Check if API scope is avalaible for application.
 
-        Useful for applications which declare ``Optional`` scopes, to check if they are allowed for them.
+        Useful for applications that declare optional scopes to check if they are allowed.
         """
         if self.check_capabilities("app_ecosystem_v2"):
             return False

pyproject.toml

@@ -71,6 +71,7 @@ dev = [
   "selenium",
 ]
 docs = [
+  "autodoc_pydantic>=2.0.1",
   "nc_py_api[app]",
   "sphinx>=6.2",
   "sphinx-copybutton",