From 3f59900c0dce130bd79c34c45b32699d80a3f9d1 Mon Sep 17 00:00:00 2001
From: Sveinung Gundersen <sveinugu@gmail.com>
Date: Tue, 31 Oct 2023 20:24:48 +0100
Subject: [PATCH] Update portray to forked version and add support for
 readthedocs

---
 .readthedocs.yaml                           | 11 +++--
 mkdocs.yml                                  | 32 ++++++++++++++
 pyproject.toml                              | 28 +-----------
 scripts/generate_portray_docs.py            | 49 +++++++++++++++++++++
 scripts/generate_portray_docs_in_browser.py | 24 ----------
 5 files changed, 87 insertions(+), 57 deletions(-)
 create mode 100644 mkdocs.yml
 create mode 100755 scripts/generate_portray_docs.py
 delete mode 100755 scripts/generate_portray_docs_in_browser.py

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 727de18d..aa608ef7 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -8,18 +8,17 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.10"
-  jobs:
-    post_create_environment:
+  commands:
       # Install poetry
       # https://python-poetry.org/docs/#installing-manually
       - pip install poetry==1.4.0
+
       # Tell poetry to not use a virtual environment
       - poetry config virtualenvs.create false
-    post_install:
+
       # Install dependencies with 'docs' dependency group
       # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
       - poetry install --with docs
 
-
-mkdocs:
-  configuration: pyproject.toml
+      # Generate documentation
+      - python scripts/generate_portray_docs for_readthedocs
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..863abbfe
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,32 @@
+site_name: Omnipy
+theme:
+  name: material
+  custom_dir: docs/overrides
+#  features:
+#    - content.code.annotation
+#    - navigation.tabs
+#    - search.highlight
+#    - toc.integrate
+  language: en
+  palette:
+    - scheme: omnipy
+extra_css:
+  - stylesheets/extra.css
+markdown_extensions:
+  - admonition
+  - codehilite
+  - extra
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+
+#markdown_extensions:
+#  - admonition
+#  - attr_list
+#  - footnotes
+#  - md_in_html
diff --git a/pyproject.toml b/pyproject.toml
index 9afd6af0..ba437531 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -51,7 +51,7 @@ furo = "^2022.12.7"
 sphinx = "^6.1.3"
 sphinx-autoapi = "^2.0.1"
 sphinx-copybutton = "^0.5.1"
-portray = "^1.8.0"
+portray = {git = "https://github.com/HeinrichAD/portray.git"}
 docstring-parser = "^0.15"
 pymdown-extensions = "^10.0.1"
 
@@ -137,31 +137,5 @@ testpaths = [
 docs_dir = "docs/portray"
 directory = "."
 
-[[tool.portray.extra_markdown_extensions]]
-[tool.portray.extra_markdown_extensions."pymdownx.highlight"]
-anchor_linenums = true
-line_spans = "__span"
-pygments_lang_class = true
-
-[tool.portray.mkdocs]
-extra_css = ["stylesheets/extra.css"]
-markdown_extensions = [
-    "admonition",
-    "codehilite",
-    "extra",
-    "pymdownx.details",
-    "pymdownx.inlinehilite",
-    "pymdownx.snippets",
-    "pymdownx.superfences",
-]
-
-[tool.portray.mkdocs.theme]
-#favicon = "art/logo_small.png"
-#logo = "art/logo_small.png"
-name = "material"
-custom_dir = "docs/overrides"
-palette = {scheme = "omnipy"}
-
-
 [tool.portray.pdocs]
 template_dir = "docs/templates/pdocs"
diff --git a/scripts/generate_portray_docs.py b/scripts/generate_portray_docs.py
new file mode 100755
index 00000000..aa1ad6f3
--- /dev/null
+++ b/scripts/generate_portray_docs.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+from enum import Enum
+import os
+
+import pdocs.doc
+from portray import api as portray_api
+import typer
+
+
+def _is_exported(ident_name):
+    return not ident_name.startswith("_") or ident_name in [
+        '__enter__',
+        '__exit__',
+        '__cmp__',
+        '__eq__',
+        '__getattr__',
+        '__setattr__',
+        '__getitem_',
+        '__setitem__',
+        '__delitem__',
+        '__iter__',
+        '__call__'
+    ]
+
+
+pdocs.doc._is_exported = _is_exported
+
+
+class Command(str, Enum):
+    IN_BROWSER = 'in_browser'
+    AS_HTML = 'as_html'
+    FOR_READTHEDOCS = 'for_readthedocs'
+    # ON_GITHUB_PAGES = 'on_github_pages'
+
+
+def main(cmd: Command):
+    if cmd == Command.IN_BROWSER:
+        portray_api.in_browser()
+    if cmd == Command.AS_HTML:
+        portray_api.as_html()
+    if cmd == Command.FOR_READTHEDOCS:
+        readthedocs_path = os.getenv('READTHEDOCS_OUTPUT')
+        portray_api.as_html(output_dir=os.path.join(readthedocs_path, 'html'))
+    # elif cmd == Command.ON_GITHUB_PAGES:
+    #     portray_api.on_github_pages()
+
+
+if __name__ == '__main__':
+    typer.run(main)
diff --git a/scripts/generate_portray_docs_in_browser.py b/scripts/generate_portray_docs_in_browser.py
deleted file mode 100755
index 300291a2..00000000
--- a/scripts/generate_portray_docs_in_browser.py
+++ /dev/null
@@ -1,24 +0,0 @@
-#!/usr/bin/env python
-import pdocs.doc
-from portray import api as portray_api
-
-
-def _is_exported(ident_name):
-    return not ident_name.startswith("_") or ident_name in [
-        '__enter__',
-        '__exit__',
-        '__cmp__',
-        '__eq__',
-        '__getattr__',
-        '__setattr__',
-        '__getitem_',
-        '__setitem__',
-        '__delitem__',
-        '__iter__',
-        '__call__'
-    ]
-
-
-pdocs.doc._is_exported = _is_exported
-
-portray_api.in_browser()