Python API for robocorp.com/docs (#1072)

* docs: add support for markdown output * dialogs: update outdated dependencies * Bump docgen version * fixup! dialogs: update outdated dependencies
robocorp · Oct 11, 2023 · 5850242 · 5850242
1 parent 6814398
commit 5850242
Show file tree

Hide file tree

Showing 88 changed files with 1,922 additions and 3,240 deletions.
diff --git a/.github/workflows/dialogs.yaml b/.github/workflows/dialogs.yaml
@@ -49,6 +49,7 @@ jobs:
           - name: "windows-py310"
             python: "3.10"
             os: windows-latest
+
           - name: "ubuntu-py38"
             python: "3.8"
             os: ubuntu-latest
@@ -58,6 +59,7 @@ jobs:
           - name: "ubuntu-py310"
             python: "3.10"
             os: ubuntu-latest
+
           - name: "macos-py38"
             python: "3.8"
             os: macos-latest

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -46,6 +46,8 @@ jobs:
         run: invoke install
       - name: Build HTML documentation
         run: invoke docs
+      - name: Build markdown documentation
+        run: invoke docs.python-markdown
       - name: Publish HTML documentation
         if: success()
         uses: peaceiris/actions-gh-pages@v3

diff --git a/docs/source/_ext/libdoc_markdown/__init__.py b/docs/source/_ext/libdoc_markdown/__init__.py
@@ -0,0 +1,41 @@
+import traceback
+from robotlibcore import HybridCore
+from sphinx.application import Sphinx
+from .robot import RstFormatter
+
+IS_ROBOT_DOC = False  # Global flag for autodoc callbacks
+
+
+def setup(app: Sphinx):
+    app.setup_extension('sphinx.ext.autodoc')
+    app.connect('autodoc-process-docstring', _process_docstring)
+    app.add_config_value('libdoc_markdown', False, 'env')
+
+
+def _process_docstring(app, what, name, obj, options, lines):
+    if not app.config.libdoc_markdown:
+        return
+
+    if what == "class":
+        if fmt := getattr(obj, "ROBOT_LIBRARY_DOC_FORMAT", "ROBOT"):
+            global IS_ROBOT_DOC
+            IS_ROBOT_DOC = fmt.strip().upper() == "ROBOT"
+
+        if issubclass(obj, HybridCore):
+            print(f"Detected libcore: {name}")
+            _patch_libcore(obj)
+
+    if IS_ROBOT_DOC and obj.__doc__:
+        output = RstFormatter().format(obj.__doc__)
+        output.replace("%TOC%", "")
+        lines[:] = output.splitlines()
+
+
+def _patch_libcore(klass):
+    try:
+        library = klass()
+        for name in library.get_keyword_names():
+            func = getattr(library, name)
+            setattr(klass, func.__name__, func)
+    except Exception:
+        traceback.print_exc()
diff --git a/docs/source/_ext/libdoc_markdown/robot.py b/docs/source/_ext/libdoc_markdown/robot.py
@@ -0,0 +1,139 @@
+from robot.utils.htmlformatters import (
+    HtmlFormatter,
+    LinkFormatter as HtmlLinkFormatter,
+    LineFormatter as HtmlLineFormatter,
+    RulerFormatter as HtmlRulerFormatter,
+    HeaderFormatter as HtmlHeaderFormatter,
+    ParagraphFormatter as HtmlParagraphFormatter,
+    TableFormatter as HtmlTableFormatter,
+    PreformattedFormatter as HtmlPreformattedFormatter,
+    ListFormatter as HtmlListFormatter,
+)
+
+
+class LinkFormatter(HtmlLinkFormatter):
+    def _get_link(self, href, content=None):
+        return "`%s <%s>`_" % (content or href, self._quot(href))
+
+
+class LineFormatter(HtmlLineFormatter):
+    def __init__(self):
+        super().__init__()
+        self._formatters = [
+            ("*", self._format_bold),
+            ("_", self._format_italic),
+            ("``", self._format_code),
+            ("", LinkFormatter().format_link),
+        ]
+
+    def _format_bold(self, line):
+        return self._bold.sub("\\1**\\3**", line)
+
+    def _format_italic(self, line):
+        return self._italic.sub("\\1*\\3*", line)
+
+    def _format_code(self, line):
+        return self._code.sub("\\1``\\3``", line)
+
+
+class RulerFormatter(HtmlRulerFormatter):
+    def format_line(self, line):
+        return "----"
+
+
+class HeaderFormatter(HtmlHeaderFormatter):
+    def format_line(self, line):
+        # NB: Using rST structural elements shouldn't end up in docstrings,
+        #     let's just use bold here instead
+        _, text = self.match(line).groups()
+        return f"\n**{text}**\n"
+
+
+class ParagraphFormatter(HtmlParagraphFormatter):
+    _format_line = LineFormatter().format
+
+    def format(self, lines):
+        paragraph = self._format_line(" ".join(lines))
+        return f"\n{paragraph}\n"
+
+
+class TableFormatter(HtmlTableFormatter):
+    _format_cell_content = LineFormatter().format
+
+    def _format_table(self, rows):
+        if not rows:
+            return ""
+
+        has_heading = False
+        widths = []
+
+        for row_idx in range(len(rows)):
+            row = rows[row_idx]
+
+            for column_idx in range(len(row)):
+                cell = row[column_idx]
+
+                if row_idx == 0 and cell.startswith("=") and cell.endswith("="):
+                    cell = cell[1:-1].strip()
+                    has_heading = True
+
+                cell = self._format_cell_content(cell)
+                row[column_idx] = cell
+
+                if len(widths) <= column_idx:
+                    widths.append(len(cell))
+                else:
+                    widths[column_idx] = max(len(cell), widths[column_idx])
+
+        table = []
+        delimiter = ["=" * width for width in widths]
+
+        def add_row(row):
+            table.append(
+                " ".join(cell.ljust(width) for cell, width in zip(row, widths))
+            )
+
+        add_row(delimiter)
+        if has_heading:
+            add_row(rows.pop(0))
+        else:
+            add_row([""] * len(widths))
+        add_row(delimiter)
+        for row in rows:
+            add_row(row)
+        add_row(delimiter)
+
+        return "\n".join(table)
+
+
+class PreformattedFormatter(HtmlPreformattedFormatter):
+    _format_line = LineFormatter().format
+
+    def format(self, lines):
+        lines = ["   {}".format(self._format_line(line[2:])) for line in lines]
+        return "\n".join(["::", "", *lines])
+
+
+class ListFormatter(HtmlListFormatter):
+    _format_item = LineFormatter().format
+
+    def format(self, lines):
+        items = []
+        for line in self._combine_lines(lines):
+            item = self._format_item(line)
+            items.append(f"- {item}")
+
+        return "\n".join([""] + items + [""])
+
+
+class RstFormatter(HtmlFormatter):
+    def __init__(self):
+        super().__init__()
+        self._formatters = [
+            TableFormatter(),
+            PreformattedFormatter(),
+            ListFormatter(),
+            HeaderFormatter(),
+            RulerFormatter(),
+        ]
+        self._formatters.append(ParagraphFormatter(self._formatters[:]))
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,6 +22,12 @@
 
 # -- General configuration ---------------------------------------------------
 
+# Add local extensions to PYTHONPATH
+import sys
+from pathlib import Path
+
+sys.path.append(str(Path(".", "_ext").absolute()))
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -30,6 +36,7 @@
     "sphinx.ext.todo",
     "sphinx_markdown_builder",
     "sphinx_issues",
+    "libdoc_markdown",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/libraries/archive/python.rst b/docs/source/libraries/archive/python.rst
@@ -6,8 +6,7 @@ Python API
 Archive
 *******
 
-.. automodule:: RPA.Archive
+.. autoclass:: RPA.Archive.Archive
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/assistant/python.rst b/docs/source/libraries/assistant/python.rst
@@ -6,8 +6,7 @@ Python API
 Assistant
 *********
 
-.. automodule:: RPA.Assistant
+.. autoclass:: RPA.Assistant.Assistant
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/browser_selenium/python.rst b/docs/source/libraries/browser_selenium/python.rst
@@ -6,8 +6,8 @@ Python API
 Browser.Selenium
 ****************
 
-.. automodule:: RPA.Browser.Selenium
+.. autoclass:: RPA.Browser.Selenium.Selenium
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
+
diff --git a/docs/source/libraries/calendar/python.rst b/docs/source/libraries/calendar/python.rst
@@ -6,8 +6,7 @@ Python API
 Calendar
 ********
 
-.. automodule:: RPA.Calendar
+.. autoclass:: RPA.Calendar.Calendar
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/cloud_aws/python.rst b/docs/source/libraries/cloud_aws/python.rst
@@ -6,8 +6,7 @@ Python API
 AWS
 ***
 
-.. automodule:: RPA.Cloud.AWS
+.. autoclass:: RPA.Cloud.AWS.AWS
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/cloud_azure/python.rst b/docs/source/libraries/cloud_azure/python.rst
@@ -6,7 +6,6 @@ Python API
 Azure
 *****
 
-.. automodule:: RPA.Cloud.Azure
+.. autoclass:: RPA.Cloud.Azure.Azure
    :members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/cloud_google/python.rst b/docs/source/libraries/cloud_google/python.rst
@@ -6,8 +6,7 @@ Python API
 Google
 ******
 
-.. automodule:: RPA.Cloud.Google
+.. autoclass:: RPA.Cloud.Google.Google
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/crypto/python.rst b/docs/source/libraries/crypto/python.rst
@@ -6,8 +6,7 @@ Python API
 Crypto
 ******
 
-.. automodule:: RPA.Crypto
+.. autoclass:: RPA.Crypto.Crypto
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/database/python.rst b/docs/source/libraries/database/python.rst
@@ -6,8 +6,7 @@ Python API
 Database
 ********
 
-.. automodule:: RPA.Database
+.. autoclass:: RPA.Database.Database
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/desktop/python.rst b/docs/source/libraries/desktop/python.rst
@@ -6,8 +6,7 @@ Python API
 Desktop
 *******
 
-.. automodule:: RPA.Desktop
+.. autoclass:: RPA.Desktop.Desktop
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/desktop_clipboard/python.rst b/docs/source/libraries/desktop_clipboard/python.rst
@@ -6,8 +6,7 @@ Python API
 Clipboard
 *********
 
-.. automodule:: RPA.Desktop.Clipboard
+.. autoclass:: RPA.Desktop.Clipboard.Clipboard
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/desktop_operatingsystem/python.rst b/docs/source/libraries/desktop_operatingsystem/python.rst
@@ -6,8 +6,7 @@ Python API
 OperatingSystem
 ***************
 
-.. automodule:: RPA.Desktop.OperatingSystem
+.. autoclass:: RPA.Desktop.OperatingSystem.OperatingSystem
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/desktop_windows/python.rst b/docs/source/libraries/desktop_windows/python.rst
@@ -6,8 +6,7 @@ Python API
 Windows
 ********
 
-.. automodule:: RPA.Desktop.Windows
+.. autoclass:: RPA.Desktop.Windows.Windows
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/dialogs/python.rst b/docs/source/libraries/dialogs/python.rst
@@ -6,8 +6,7 @@ Python API
 Dialogs
 *******
 
-.. automodule:: RPA.Dialogs
+.. autoclass:: RPA.Dialogs.Dialogs
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/documentai/python.rst b/docs/source/libraries/documentai/python.rst
@@ -6,8 +6,7 @@ Python API
 DocumentAI
 **********
 
-.. automodule:: RPA.DocumentAI.DocumentAI
+.. autoclass:: RPA.DocumentAI.DocumentAI.DocumentAI
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/documentai_base64ai/python.rst b/docs/source/libraries/documentai_base64ai/python.rst
@@ -6,8 +6,7 @@ Python API
 Base64AI
 ********
 
-.. automodule:: RPA.DocumentAI.Base64AI
+.. autoclass:: RPA.DocumentAI.Base64AI.Base64AI
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/libraries/documentai_nanonets/python.rst b/docs/source/libraries/documentai_nanonets/python.rst
@@ -6,8 +6,7 @@ Python API
 Nanonets
 ********
 
-.. automodule:: RPA.DocumentAI.Nanonets
+.. autoclass:: RPA.DocumentAI.Nanonets.Nanonets
    :members:
    :inherited-members:
    :undoc-members:
-   :show-inheritance: