diff --git a/libshortfin/docs/README.md b/libshortfin/docs/README.md new file mode 100644 index 000000000..3d993628a --- /dev/null +++ b/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 +``` diff --git a/libshortfin/docs/conf.py b/libshortfin/docs/conf.py new file mode 100644 index 000000000..635478bc1 --- /dev/null +++ b/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"] diff --git a/libshortfin/docs/index.rst b/libshortfin/docs/index.rst new file mode 100644 index 000000000..892c59db5 --- /dev/null +++ b/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` diff --git a/libshortfin/docs/reference.rst b/libshortfin/docs/reference.rst new file mode 100644 index 000000000..fec33ed79 --- /dev/null +++ b/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 diff --git a/libshortfin/docs/requirements.txt b/libshortfin/docs/requirements.txt new file mode 100644 index 000000000..1aef75db6 --- /dev/null +++ b/libshortfin/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx==7.4.7 +sphinx_rtd_theme==2.0.0 diff --git a/libshortfin/python/array_binding.cc b/libshortfin/python/array_binding.cc index b7b89cb3a..3c5ba245c 100644 --- a/libshortfin/python/array_binding.cc +++ b/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