Add API Reference documentation as Github pages

.github/workflows/docs-publish.yml

@@ -0,0 +1,38 @@
+name: Build sphinx documentation
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main", "develop"]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10.x"
+      - uses: abatilo/actions-poetry@v2
+      - name: Install dependencies
+        run: |
+          poetry install
+      - name: Sphinx build HTML
+        run: |
+          poetry run sphinx-apidoc -f -e -M -o ./docs/source/ ./ayon_api/         
+      - name: Sphinx build HTML
+        run: |
+          poetry run sphinx-build -M html ./docs/source ./docs/build
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build/html/
+          force_orphan: true

ayon_api/_api.py

@@ -3277,9 +3277,10 @@ def delete_version(*args, **kwargs):
 def get_representations(*args, **kwargs):
     """Get representation entities based on passed filters from server.
 
-    Todos:
+    .. todo::
+
         Add separated function for 'names_by_version_ids' filtering.
-            Because can't be combined with others.
+        Because can't be combined with others.
 
     Args:
         project_name (str): Name of project where to look for versions.
@@ -3289,7 +3290,7 @@ def get_representations(*args, **kwargs):
             names used for representation filtering.
         version_ids (Optional[Iterable[str]]): Version ids used for
             representation filtering. Versions are parents of
-                representations.
+            representations.
         names_by_version_ids (Optional[bool]): Find representations
             by names and version ids. This filter discard all
             other filters.
@@ -4028,7 +4029,10 @@ def delete_link(*args, **kwargs):
 def get_entities_links(*args, **kwargs):
     """Helper method to get links from server for entity types.
 
-    Example output::
+    .. highlight:: text
+    .. code-block:: text
+
+        Example output
         {
             "59a212c0d2e211eda0e20242ac120001": [
                 {
@@ -4049,12 +4053,12 @@ def get_entities_links(*args, **kwargs):
     Args:
         project_name (str): Project where links are.
         entity_type (Literal["folder", "task", "product",
-            "version", "representations"]): Entity type.
+        |    "version", "representations"]): Entity type.
         entity_ids (Optional[Iterable[str]]): Ids of entities for which
-            links should be received.
+        |    links should be received.
         link_types (Optional[Iterable[str]]): Link type filters.
         link_direction (Optional[Literal["in", "out"]]): Link direction
-            filter.
+        |    filter.
         link_names (Optional[Iterable[str]]): Link name filters.
         link_name_regex (Optional[str]): Regex filter for link name.
 

ayon_api/entity_hub.py

@@ -1029,14 +1029,17 @@ class EntityData(dict):
 
     It is not possible to store 'None' to root key. In that case the key is
     not stored, and removed if existed on entity.
-
     To be able to store 'None' value use nested data structure:
-    {
-        "sceneInfo": {
-             "description": None,
-             "camera": "camera1"
+
+    .. highlight:: text
+    .. code-block:: text
+
+        {
+            "sceneInfo": {
+                "description": None,
+                "camera": "camera1"
+            }
         }
-    }
 
     """
     def __init__(self, *args, **kwargs):

ayon_api/server_api.py

@@ -6248,9 +6248,10 @@ def get_representations(
     ):
         """Get representation entities based on passed filters from server.
 
-        Todos:
+        .. todo::
+
             Add separated function for 'names_by_version_ids' filtering.
-                Because can't be combined with others.
+            Because can't be combined with others.
 
         Args:
             project_name (str): Name of project where to look for versions.
@@ -6260,7 +6261,7 @@ def get_representations(
                 names used for representation filtering.
             version_ids (Optional[Iterable[str]]): Version ids used for
                 representation filtering. Versions are parents of
-                    representations.
+                representations.
             names_by_version_ids (Optional[bool]): Find representations
                 by names and version ids. This filter discard all
                 other filters.
@@ -7765,7 +7766,10 @@ def get_entities_links(
     ):
         """Helper method to get links from server for entity types.
 
-        Example output::
+        .. highlight:: text
+        .. code-block:: text
+
+            Example output:
             {
                 "59a212c0d2e211eda0e20242ac120001": [
                     {
@@ -7785,13 +7789,10 @@ def get_entities_links(
 
         Args:
             project_name (str): Project where links are.
-            entity_type (Literal["folder", "task", "product",
-                "version", "representations"]): Entity type.
-            entity_ids (Optional[Iterable[str]]): Ids of entities for which
-                links should be received.
+            entity_type (Literal["folder", "task", "product", "version", "representations"]): Entity type.
+            entity_ids (Optional[Iterable[str]]): Ids of entities for which links should be received.
             link_types (Optional[Iterable[str]]): Link type filters.
-            link_direction (Optional[Literal["in", "out"]]): Link direction
-                filter.
+            link_direction (Optional[Literal["in", "out"]]): Link direction filter.
             link_names (Optional[Iterable[str]]): Link name filters.
             link_name_regex (Optional[str]): Regex filter for link name.
 

ayon_api/utils.py

@@ -412,16 +412,17 @@ def validate_url(url, timeout=None):
     Function will try to autofix url thus will return modified url when
     connection to server works.
 
-    ```python
-    my_url = "my.server.url"
-    try:
-        # Store new url
-        validated_url = validate_url(my_url)
+    .. highlight:: python
+    .. code-block:: python
+
+        my_url = "my.server.url"
+        try:
+            # Store new url
+            validated_url = validate_url(my_url)
 
-    except UrlError:
-        # Handle invalid url
-        ...
-    ```
+        except UrlError:
+            # Handle invalid url
+            ...
 
     Args:
         url (str): Server url.

docs/make_api.bat

@@ -2,4 +2,5 @@
 
 pushd %~dp0
 
-poetry run sphinx-apidoc -f -o ../docs/source/ ../ ../tests ../*setup*
+poetry run sphinx-apidoc -f -e -M -o .\source\ ..\ayon_api\
+

docs/source/conf.py

@@ -27,9 +27,9 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc',
+extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
@@ -41,6 +41,7 @@
 ]
 
 # -- Napoleon settings -------------------------------------------------------
+add_module_names = False
 
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False
@@ -49,9 +50,9 @@
 napoleon_include_special_with_doc = False
 napoleon_use_admonition_for_examples = True
 napoleon_use_admonition_for_notes = True
-napoleon_use_admonition_for_references = False
+napoleon_use_admonition_for_references = True
 napoleon_use_ivar = True
-napoleon_use_param = False
+napoleon_use_param = True
 napoleon_use_rtype = True
 napoleon_preprocess_types = True
 napoleon_attr_annotations = True
@@ -67,7 +68,14 @@
 html_theme = "revitron_sphinx_theme"
 html_static_path = ['_static']
 html_logo = './_static/AYON_blackG_dot.svg'
+html_favicon = './_static/favicon.ico'
 
+html_context = {
+    'landing_page': {
+    }
+}
+myst_footnote_transition = False
+html_sidebars = {}
 
 html_theme_options = {
     'color_scheme': '',
@@ -79,4 +87,4 @@
     'includehidden': False,
     'titles_only': False,
     'github_url': 'https://github.com/ynput/ayon-python-api',
-}
+}