[libshortfin] Enable building docs with Sphinx

libshortfin/docs/README.md

@@ -0,0 +1,20 @@
+# Python API Docs
+
+Documentation for the Python API is build with Sphinx under this directory.
+
+## Building docs
+
+The Python modules will be automatically imported if installed or if the build
+is located at `../build`, relative to this file.
+
+### Install dependencies
+
+```shell
+python3 -m pip install -r requirements.txt
+```
+
+### Build the docs
+
+```shell
+sphinx-build -b html . _build
+```

libshortfin/docs/conf.py

@@ -0,0 +1,42 @@
+# Copyright 2024 Advanced Micro Devices, Inc.
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+try:
+    import _shortfin_default
+except ImportError:
+    sys.path.insert(0, os.path.abspath("../build/python/"))
+    import _shortfin_default
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "libshortfin"
+copyright = "2024, Advanced Micro Devices, Inc"
+author = "libshortfin Authors"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

libshortfin/docs/index.rst

@@ -0,0 +1,27 @@
+.. Copyright 2024 Advanced Micro Devices, Inc.
+
+.. libshortfin documentation master file, created by
+   sphinx-quickstart on Fri Sep  6 16:31:45 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to libshortfin's documentation!
+=======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   reference
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

libshortfin/docs/reference.rst

@@ -0,0 +1,58 @@
+.. Copyright 2024 Advanced Micro Devices, Inc.
+
+.. py:module:: _shortfin_default.lib
+
+.. _reference:
+
+API Reference
+=============
+
+Array
+--------------
+.. automodule:: _shortfin_default.lib.array
+.. autoclass:: DType
+.. autoclass:: storage
+    :members:
+.. autoclass:: base_array
+.. autoclass:: device_array
+
+Local
+--------------
+
+.. automodule:: _shortfin_default.lib.local
+
+.. autoclass:: SystemBuilder
+.. autoclass:: System
+.. autoclass:: Node
+.. autoclass:: Device
+.. autoclass:: DeviceAffinity
+.. autoclass:: Program
+.. autoclass:: ProgramFunction
+    :members:
+.. autoclass:: ProgramModule
+.. autoclass:: ProgramInvocation
+.. autoclass:: Fiber
+.. autoclass:: ScopedDevice
+.. autoclass:: Worker
+.. autoclass:: Process
+.. autoclass:: CompletionEvent
+.. autoclass:: Message
+.. autoclass:: Queue
+.. autoclass:: QueueWriter
+.. autoclass:: QueueReader
+.. autoclass:: Future
+.. autoclass:: VoidFuture
+.. autoclass:: MessageFuture
+
+
+AMD GPU
+^^^^^^^
+.. automodule:: _shortfin_default.lib.local.amdgpu
+.. autoclass:: SystemBuilder
+.. autoclass:: AMDGPUDevice
+
+Host
+^^^^^^^
+.. automodule:: _shortfin_default.lib.local.host
+.. autoclass:: CPUSystemBuilder
+.. autoclass:: HostCPUDevice

libshortfin/docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==7.4.7
+sphinx_rtd_theme==2.0.0

libshortfin/python/array_binding.cc

@@ -114,10 +114,10 @@ static const char DOCSTRING_STORAGE_MAP[] =
 
 Support kwargs of:
 
-read: Enables read access to the mapped memory.
-write: Enables write access to the mapped memory and will flush upon close
+| read: Enables read access to the mapped memory.
+| write: Enables write access to the mapped memory and will flush upon close
   (for non-unified memory systems).
-discard: Indicates that the entire memory map should be treated as if it will
+| discard: Indicates that the entire memory map should be treated as if it will
   be overwritten. Initial contents will be undefined. Implies `write=True`.
 
 Mapping memory for access from the host requires a compatible buffer that has