From a056b8455f80a145839177102288e1f1d2b8ebe3 Mon Sep 17 00:00:00 2001 From: Cathal McCabe Date: Tue, 11 Oct 2022 15:20:33 +0100 Subject: [PATCH] Update docs, add RTD YML (#1398) --- .readthedocs.yml | 29 +++++++++++++++++++ docs/requirements.txt | 4 ++- docs/source/conf.py | 12 ++++---- docs/source/index.rst | 16 +++++----- .../pynq_package/pynq.lib/pynq.lib.wifi.rst | 2 ++ docs/source/pynq_package/pynq.metadata.rst | 18 ++++++------ .../pynq.metadata.clock_dict_view.rst | 2 +- .../pynq.metadata.gpio_dict_view.rst | 2 +- .../pynq.metadata.hierarchy_dict_view.rst | 2 +- ...nq.metadata.interrupt_controllers_view.rst | 2 +- .../pynq.metadata.ip_dict_view.rst | 2 +- .../pynq.metadata.mem_dict_view.rst | 2 +- .../pynq.metadata.metadata_view.rst | 2 +- docs/source/pynq_package/pynq.pl_server.rst | 1 - 14 files changed, 65 insertions(+), 31 deletions(-) create mode 100644 .readthedocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..b0ff741360 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,29 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-20.04 + tools: + python: "3.9" + # You can also specify other tool versions: + # nodejs: "16" + # rust: "1.55" + # golang: "1.17" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# If using Sphinx, optionally build your docs in additional formats such as PDF +# formats: +# - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 3350e1eae8..f05d36e809 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -11,4 +11,6 @@ ipython pytest netifaces pandas -sphinx_copybutton \ No newline at end of file +sphinx_copybutton +git+https://github.com/xilinx/pynq-metadata@main#egg=pynqmetadata +git+https://github.com/xilinx/pynq-utils@main#egg=pynqutils \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 78400ccb00..74225ad3c4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -68,9 +68,9 @@ def __getattr__(cls, name): master_doc = 'index' # General information about the project. -project = 'PYNQ: Python productivity for Xilinx platforms' -copyright = '2022, AMD-Xilinx' -author = 'AMD-Xilinx' +project = 'PYNQ: Python productivity for Adaptive Computing platforms' +copyright = '2022, Advanced Micro Devices, Inc.' +author = 'AMD' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -277,7 +277,7 @@ def __getattr__(cls, name): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'pythononzynqpynq', 'Python productivity for Zynq (Pynq) Documentation', + (master_doc, 'pythononzynqpynq', 'PYNQ Documentation', [author], 1) ] @@ -291,8 +291,8 @@ def __getattr__(cls, name): # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'PythononZynqPynq', 'Python productivity for Zynq (Pynq) Documentation', - author, 'PythononZynqPynq', 'One line description of project.', + (master_doc, 'PythononZynqPynq', 'Pynq Documentation', + author, 'PythononZynqPynq', 'Python Productivity for Adaptive Computing platforms.', 'Miscellaneous'), ] diff --git a/docs/source/index.rst b/docs/source/index.rst index ea18e5f696..8f05bb4021 100755 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,13 +7,14 @@ PYNQ Introduction ***************** -PYNQ is an open-source project from Xilinx®. It provides a Jupyter-based -framework with Python APIs for using Xilinx platforms. -PYNQ supports Zynq® and Zynq Ultrascale+™, Zynq RFSoC™, Alveo™ and AWS-F1 -instances. +PYNQ is an open-source project from AMD. It provides a Jupyter-based +framework with Python APIs for using AMD Xilinx Adaptive Computing platforms. +PYNQ supports Zynq® and Zynq Ultrascale+™, Zynq RFSoC™, Kria™ SOMs, Alveo™ +and AWS-F1 instances. PYNQ enables architects, engineers -and programmers who design embedded systems to use Zynq devices, without having +and programmers who design embedded systems to use Adaptive Computing +platforms, without having to use ASIC-style design tools to design programmable logic circuits. @@ -57,7 +58,8 @@ PYNQ Background operating system. This goal is achieved by adopting a web-based architecture, which is also browser agnostic. We incorporate the open-source Jupyter notebook infrastructure to run an Interactive Python (IPython) kernel and a - web server directly on the ARM processor of the Zynq device. The web server + web server directly on the ARM processor of the Zynq device, or host processor + in the case of Alveo and AWS-F1. The web server brokers access to the kernel via a suite of browser-based tools that provide a dashboard, bash terminal, code editors and Jupyter notebooks. The browser tools are implemented with a combination of JavaScript, HTML and CSS and run @@ -67,7 +69,7 @@ Summary ####### PYNQ is the first project to combine the following elements to simplify and -improve Xilinx system design: +improve Adaptive Computing system design: #. A high-level productivity language (Python in this case) #. FPGA overlays with extensive APIs exposed as Python libraries diff --git a/docs/source/pynq_package/pynq.lib/pynq.lib.wifi.rst b/docs/source/pynq_package/pynq.lib/pynq.lib.wifi.rst index f5a16a77f7..904640e574 100644 --- a/docs/source/pynq_package/pynq.lib/pynq.lib.wifi.rst +++ b/docs/source/pynq_package/pynq.lib/pynq.lib.wifi.rst @@ -1,3 +1,5 @@ +.. _pynq-lib-wifi: + pynq.lib.wifi Module ==================== diff --git a/docs/source/pynq_package/pynq.metadata.rst b/docs/source/pynq_package/pynq.metadata.rst index 76b230c9fe..186b8d8f35 100644 --- a/docs/source/pynq_package/pynq.metadata.rst +++ b/docs/source/pynq_package/pynq.metadata.rst @@ -1,7 +1,7 @@ .. _pynq-metadata: pynq.metadata Package -====================== +===================== The pynq.metadata module contains the required modules for managing the Overlay metadata. The metadata can be extracted from a HWH file or an XSA and contains the complete hardware @@ -21,11 +21,11 @@ Modules: .. toctree:: :hidden: - pynq.metadata/pynq.pl_server.runtime_metadata_parser - pynq.metadata/pynq.pl_server.metadata_view - pynq.metadata/pynq.pl_server.ip_dict_view - pynq.metadata/pynq.pl_server.mem_dict_view - pynq.metadata/pynq.pl_server.interrupt_controllers_view - pynq.metadata/pynq.pl_server.hierarchy_dict_view - pynq.metadata/pynq.pl_server.gpio_dict_view - pynq.metadata/pynq.pl_server.clock_dict_view \ No newline at end of file + pynq.metadata/pynq.metadata.runtime_metadata_parser + pynq.metadata/pynq.metadata.metadata_view + pynq.metadata/pynq.metadata.ip_dict_view + pynq.metadata/pynq.metadata.mem_dict_view + pynq.metadata/pynq.metadata.interrupt_controllers_view + pynq.metadata/pynq.metadata.hierarchy_dict_view + pynq.metadata/pynq.metadata.gpio_dict_view + pynq.metadata/pynq.metadata.clock_dict_view \ No newline at end of file diff --git a/docs/source/pynq_package/pynq.metadata/pynq.metadata.clock_dict_view.rst b/docs/source/pynq_package/pynq.metadata/pynq.metadata.clock_dict_view.rst index d0c64b26e4..5df02fdadc 100644 --- a/docs/source/pynq_package/pynq.metadata/pynq.metadata.clock_dict_view.rst +++ b/docs/source/pynq_package/pynq.metadata/pynq.metadata.clock_dict_view.rst @@ -1,7 +1,7 @@ .. _pynq-metadata-clock_dict_view: pynq.metadata-clock_dict_view Module -================================================ +==================================== Provides a view onto the Metadata object that displays all configurable clocks in the system. Models a dictionary, where diff --git a/docs/source/pynq_package/pynq.metadata/pynq.metadata.gpio_dict_view.rst b/docs/source/pynq_package/pynq.metadata/pynq.metadata.gpio_dict_view.rst index 0054ae8afb..abd21cd4a3 100644 --- a/docs/source/pynq_package/pynq.metadata/pynq.metadata.gpio_dict_view.rst +++ b/docs/source/pynq_package/pynq.metadata/pynq.metadata.gpio_dict_view.rst @@ -1,7 +1,7 @@ .. _pynq-metadata-gpio_dict_view: pynq.metadata-gpio_dict_view Module -================================================ +=================================== Provides a view onto the Metadata object that displays all GPIO pins controlled by the PS. Models a dictionary where diff --git a/docs/source/pynq_package/pynq.metadata/pynq.metadata.hierarchy_dict_view.rst b/docs/source/pynq_package/pynq.metadata/pynq.metadata.hierarchy_dict_view.rst index 991b61bb71..427fd6fc03 100644 --- a/docs/source/pynq_package/pynq.metadata/pynq.metadata.hierarchy_dict_view.rst +++ b/docs/source/pynq_package/pynq.metadata/pynq.metadata.hierarchy_dict_view.rst @@ -1,7 +1,7 @@ .. _pynq-metadata-hierarchy_dict_view: pynq.metadata-hierarchy_dict_view Module -================================================ +======================================== Provides a hierarchy view onto the Metadata object that will display all hierarchies of addressable IP from the Processing System. diff --git a/docs/source/pynq_package/pynq.metadata/pynq.metadata.interrupt_controllers_view.rst b/docs/source/pynq_package/pynq.metadata/pynq.metadata.interrupt_controllers_view.rst index f78ab5e697..f04b78054e 100644 --- a/docs/source/pynq_package/pynq.metadata/pynq.metadata.interrupt_controllers_view.rst +++ b/docs/source/pynq_package/pynq.metadata/pynq.metadata.interrupt_controllers_view.rst @@ -1,7 +1,7 @@ .. _pynq-metadata-interrupt_controllers_view: pynq.metadata-interrupt_controllers_view Module -================================================ +=============================================== Provides a view onto the Metadata object that displays all the AXI interrupt controllers that are accessible from the processing system. Models a dictionary diff --git a/docs/source/pynq_package/pynq.metadata/pynq.metadata.ip_dict_view.rst b/docs/source/pynq_package/pynq.metadata/pynq.metadata.ip_dict_view.rst index 80ca62445c..5c946cd0ec 100644 --- a/docs/source/pynq_package/pynq.metadata/pynq.metadata.ip_dict_view.rst +++ b/docs/source/pynq_package/pynq.metadata/pynq.metadata.ip_dict_view.rst @@ -1,7 +1,7 @@ .. _pynq-metadata-ip_dict_view: pynq.metadata-ip_dict_view Module -=================================== +================================= Provides a view onto the Metadata object that displays all addressable IP from the Processing System. Models a dictionary, diff --git a/docs/source/pynq_package/pynq.metadata/pynq.metadata.mem_dict_view.rst b/docs/source/pynq_package/pynq.metadata/pynq.metadata.mem_dict_view.rst index 7b65ef6d60..a752a49733 100644 --- a/docs/source/pynq_package/pynq.metadata/pynq.metadata.mem_dict_view.rst +++ b/docs/source/pynq_package/pynq.metadata/pynq.metadata.mem_dict_view.rst @@ -1,7 +1,7 @@ .. _pynq-metadata-mem_dict_view: pynq.metadata-mem_dict_view Module -=================================== +================================== Provides a view onto the Metadata object that displays all memory accessible from the Processing System. Models a dictionary, diff --git a/docs/source/pynq_package/pynq.metadata/pynq.metadata.metadata_view.rst b/docs/source/pynq_package/pynq.metadata/pynq.metadata.metadata_view.rst index 189a07d9f5..6c353b9992 100644 --- a/docs/source/pynq_package/pynq.metadata/pynq.metadata.metadata_view.rst +++ b/docs/source/pynq_package/pynq.metadata/pynq.metadata.metadata_view.rst @@ -1,7 +1,7 @@ .. _pynq-metadata-metadata_view: pynq.metadata-metadata_view Module -=================================== +================================== Base class for the metadata views, contains common methods such as dictionary style setters and iterators. In PYNQ users are not supposed to access the metadata directly diff --git a/docs/source/pynq_package/pynq.pl_server.rst b/docs/source/pynq_package/pynq.pl_server.rst index da75351f4c..ed5f7c5f80 100644 --- a/docs/source/pynq_package/pynq.pl_server.rst +++ b/docs/source/pynq_package/pynq.pl_server.rst @@ -18,7 +18,6 @@ Modules: .. toctree:: :hidden: - pynq.pl_server/pynq.pl_server.server pynq.pl_server/pynq.pl_server.device pynq.pl_server/pynq.pl_server.xrt_device pynq.pl_server/pynq.pl_server.embedded_device