feat: Add an initial implementation of Sphinx docs generation

.github/workflows/notify-wiki.yml

@@ -0,0 +1,22 @@
+name: Fire Wiki Rebuild
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  notify-wiki:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 
+      NOTIFY_TOKEN: ${{ secrets.DOCS_REBUILD_TOKEN }} 
+    steps:
+      - name: Notify Wiki Repository
+        uses: convictional/trigger-workflow-and-wait@v1.6.1
+        with:
+          github_token: ${{ env.NOTIFY_TOKEN }}
+          workflow_file_name: "astro.yml" 
+          owner: Fabric-Development 
+          repo: fabric-wiki

docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+markdown:
+	sphinx-build -b markdown source build/markdown

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,42 @@
+import os
+import sys
+from recommonmark.parser import CommonMarkParser
+
+
+project = "fabric"
+release = "0.0.2"
+author = "Yousef EL-Darsh"
+copyright = "2024, Yousef EL-Darsh"
+
+sys.path.insert(0, os.path.abspath("./"))
+sys.path.insert(0, os.path.abspath("../../fabric"))
+
+extensions = [
+    "sphinx_markdown_builder",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "recommonmark",
+    "ext.fabric_types",
+    "ext.sphinx_starlight",
+    "sphinx_toolbox.more_autodoc.overloads",
+]
+
+smartquotes = False
+exclude_patterns = []
+master_doc = "fabric"
+html_permalinks = False
+html_show_sourcelink = False
+html_theme = "sphinxawesome_theme"
+html_permalinks_icon = "<span>#</span>"
+
+source_parsers = {".md": CommonMarkParser}
+source_suffix = [".rst", ".md"]
+autodoc_member_order = "bysource"
+
+# autodoc_typehints = "description"
+# autodoc_class_signature = "separated"
+autodoc_typehints_format = "short"
+autodoc_preserve_defaults = True
+add_module_names = False
+default_role = None
+autoclass_content = "both"

docs/source/ext/fabric_types.py

@@ -0,0 +1,122 @@
+# a sphinx extension for handling Fabric specific types
+import sys
+from loguru import logger
+from docutils import nodes
+from docutils.utils import unescape
+from sphinx.application import Sphinx
+from sphinx.util.inspect import signature
+from sphinx.domains.python import PyAttribute
+from sphinx.ext.autodoc import AttributeDocumenter
+
+
+class FixedText(nodes.Text):
+    def astext(self):
+        return str(unescape(self, respect_whitespace=True))
+
+
+class SignalDocumenter(AttributeDocumenter):
+    priority = 11
+    objtype = "signal"
+    directivetype = "signal"
+
+    @classmethod
+    def can_document_member(
+        cls, member: object, member_name: str, is_attr: bool, parent: object
+    ):
+        import fabric.core.service
+
+        return isinstance(member, fabric.core.service.SignalWrapper)
+
+    def add_directive_header(self, sig):
+        super().add_directive_header(sig)
+
+    def format_signature(self):
+        logger.debug(
+            f"[Ext][FabricDoc] formatting signal's signature with name {self.name}"
+        )
+        try:
+            sig = signature(self.object.func)
+            return str(sig)
+        except Exception:
+            return "<Error Documenting Signal (Report this!)>"
+
+    def should_suppress_value_header(self) -> bool:
+        return True  # no thanks
+
+    def document_members(self, all_members: bool = False) -> None:
+        return None
+
+
+class SignalDirective(PyAttribute):
+    allow_nesting = True
+
+    def needs_arglist(self) -> bool:
+        return True
+
+    def get_signature_prefix(self, sig: str) -> list[FixedText]:
+        logger.debug(f"[Ext][FabricDoc] adding signature prefix for the signal {sig}")
+        return [FixedText("signal"), FixedText(" ")]
+
+    def get_index_text(self, modname: str, name_cls: str) -> str:
+        return "signal"
+
+
+def initialize_fabric():
+    if "fabric" in sys.modules:
+        del sys.modules["fabric"]
+    if "gi" in sys.modules:
+        del sys.modules["gi"]
+
+    # PyGObject adds unwanted docstrings for types with deprecated construtors for some reason
+    # get rid of those so they won't appear in the output docs
+    import gi.overrides
+
+    old_init_wrapper = gi.overrides.deprecated_init
+
+    def new_init_wrapper(*args, **kwargs):
+        func = old_init_wrapper(*args, **kwargs)
+        setattr(func, "__doc__", None)
+        delattr(func, "__doc__")
+        return func
+
+    gi.overrides.deprecated_init = new_init_wrapper
+
+    import fabric.core.service
+
+    fabric.core.service.gi.overrides = new_init_wrapper
+
+    # fix the displayment of some fabric types
+
+    # fabric.core.service.Service = object
+    fabric.core.service.Property = lambda *_, **__: property
+    # fabric.core.service.Property.__doc__ = "    :meta private:"
+    # fabric.core.service.Signal = lambda *_, **__: None
+    # fabric.core.service.SignalWrapper.__repr__ = (
+    #     lambda self: f"Signal{signature(self.func)}"  # type: ignore
+    # )
+
+
+def skip_internals(
+    app: Sphinx,
+    what: str,
+    name: str,
+    obj: object,
+    skip: bool,
+    options: dict[str, object],
+):
+    # TODO: use an annotation instead (or a decorator for hiding internals)
+    if name.startswith(("on_", "do_")):
+        logger.debug(f"[Ext][FabricDoc] skipping internal method with name {name}")
+        return True  # "skip me"
+    if getattr(obj, "__module__", None) == "builtins":
+        return True
+    return None  # "do whatever you see right"
+
+
+def setup(app: Sphinx):
+    initialize_fabric()
+
+    app.add_autodocumenter(SignalDocumenter)
+    app.add_directive_to_domain("py", "signal", SignalDirective)
+
+    app.connect("autodoc-skip-member", skip_internals)