Setup for ReadtheDocs (#5)

* Set up documentation config for ReadtheDocs * Fix image link and markdown lint violations in README * Target develop branch for bot PRs [ROCm/rocjpeg commit: 612116e059]
2024-03-27 14:13:32 -06:00
parent 39face871e
commit bfaf0f519d
@@ -0,0 +1,18 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/docs/sphinx" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
+    target-branch: "develop"
+    labels:
+      - "dependencies"
+      - "ci:docs-only"
+    reviewers:
+      - "samjwu"
@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+   configuration: docs/conf.py
+
+formats: [htmlzip, pdf, epub]
+
+python:
+   install:
+   - requirements: docs/sphinx/requirements.txt
+
+build:
+   os: ubuntu-22.04
+   tools:
+      python: "3.8"
@@ -1,7 +1,6 @@
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)

-
-<p align="center"><img width="70%" src="docs/data/AMD_rocJPEG_Logo.png" /></p>
+<p align="center"><img width="70%" src="https://raw.githubusercontent.com/ROCm/rocJPEG/develop/docs/data/AMD_rocJPEG_Logo.png?token=GHSAT0AAAAAACQDGMWUFHBF2FTMAPZF52XAZQEP7WQ"/></p>

 rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG API, you can access the JPEG decoding features available on your GPU.

@@ -15,22 +14,26 @@ rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG AP
 ## Prerequisites

 * Linux distribution
-    * Ubuntu - `20.04` / `22.04`
-    * RHEL - `8` / `9`
-    * SLES - `15-SP5`
+  * Ubuntu - `20.04` / `22.04`
+  * RHEL - `8` / `9`
+  * SLES - `15-SP5`

 * [ROCm supported hardware](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html)
-> [!IMPORTANT] 
+
+> [!IMPORTANT]
 > `gfx908` or higher GPU required

 * Install ROCm `6.1.0` or later with [amdgpu-install](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/amdgpu-install.html): Required usecase - rocm
+
 > [!IMPORTANT]
 > `sudo amdgpu-install --usecase=rocm`

 * AMD Multimedia packages
-  ```shell
-  sudo apt install libva-amdgpu-dev libdrm-amdgpu1 mesa-amdgpu-va-drivers
-  ```
+
+```shell
+sudo apt install libva-amdgpu-dev libdrm-amdgpu1 mesa-amdgpu-va-drivers
+```
+
 > [!NOTE]
 > RPM Packages for `RHEL`/`SLES` - `libva-amdgpu-devel libdrm-amdgpu mesa-amdgpu-dri-drivers`

@@ -46,7 +49,8 @@ rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG AP
  sudo apt install pkg-config
  ```

-> [!IMPORTANT] 
+> [!IMPORTANT]
+>
 > * If using Ubuntu 22.04, you must install `libstdc++-12-dev`
 >
 >  ```shell
@@ -54,11 +58,12 @@ rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG AP
 >  ```

 >[!NOTE]
+>
 > * All package installs are shown with the `apt` package manager. Use the appropriate package manager for your operating system.
 > * To install rocJPEG with minimum requirements, follow the [quick-start](./docs/install/quick-start.rst) instructions

+### Prerequisites setup script for Linux

-#### Prerequisites setup script for Linux
 For your convenience, we provide the setup script,
 [rocJPEG-setup.py](rocJPEG-setup.py) which installs all required dependencies. Run this script only once.

@@ -105,6 +110,7 @@ sudo yum install rocjpeg rocjpeg-devel rocjpeg-test
 ```shell
 sudo zypper install rocjpeg rocjpeg-devel rocjpeg-test
 ```
+
 >[!NOTE]
 > Package install auto installs all dependencies.

@@ -198,4 +204,4 @@ page.
 * ROCm:
  * rocm-core - `6.1.0.60100-62`
  * amdgpu-core - `1:6.1.60100-1741643`
-* rocJPEG Setup Script - `V1.0`
+* rocJPEG Setup Script - `V1.0`
@@ -0,0 +1,9 @@
+build/
+_build/
+_images/
+_static/
+_templates/
+_toc.yml
+docBin/
+_doxygen/
+index.md
@@ -0,0 +1,38 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import re
+import shutil
+
+from rocm_docs import ROCmDocs
+
+shutil.copy2('../README.md','./index.md')
+
+with open('../CMakeLists.txt', encoding='utf-8') as f:
+    match = re.search(r'.*\bset\(VERSION\s+\"?([0-9.]+)[^0-9.]+', f.read())
+    if not match:
+        raise ValueError("VERSION not found!")
+    version_number = match[1]
+left_nav_title = f"rocJPEG {version_number} Documentation"
+
+# for PDF output on Read the Docs
+project = "rocJPEG Documentation"
+author = "Advanced Micro Devices, Inc."
+copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
+version = version_number
+release = version_number
+
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(left_nav_title)
+docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml")
+docs_core.enable_api_reference()
+docs_core.setup()
+
+external_projects_current_project = "rocjpeg"
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)
@@ -0,0 +1,3 @@
+html
+latex
+xml
@@ -0,0 +1,4 @@
+# License
+
+```{include} ../LICENSE
+```
@@ -0,0 +1,10 @@
+defaults:
+  numbered: False
+root: index
+subtrees:
+- caption: API Reference
+  entries:
+    - file: doxygen/html/index
+- caption: About
+  entries:
+    - file: license
@@ -0,0 +1 @@
+rocm-docs-core[api_reference]==0.38.0
@@ -0,0 +1,181 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile --resolver=backtracking requirements.in
+#
+accessible-pygments==0.0.4
+    # via pydata-sphinx-theme
+alabaster==0.7.13
+    # via sphinx
+babel==2.14.0
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.12.3
+    # via pydata-sphinx-theme
+breathe==4.35.0
+    # via rocm-docs-core
+certifi==2024.2.2
+    # via requests
+cffi==1.16.0
+    # via
+    #   cryptography
+    #   pynacl
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via
+    #   click-log
+    #   doxysphinx
+    #   sphinx-external-toc
+click-log==0.4.0
+    # via doxysphinx
+cryptography==42.0.5
+    # via pyjwt
+deprecated==1.2.14
+    # via pygithub
+docutils==0.19
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+doxysphinx==3.3.7
+    # via rocm-docs-core
+fastjsonschema==2.19.1
+    # via rocm-docs-core
+gitdb==4.0.11
+    # via gitpython
+gitpython==3.1.42
+    # via rocm-docs-core
+idna==3.6
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==7.1.0
+    # via sphinx
+importlib-resources==6.4.0
+    # via
+    #   mpire
+    #   rocm-docs-core
+jinja2==3.1.3
+    # via
+    #   myst-parser
+    #   sphinx
+libsass==0.22.0
+    # via doxysphinx
+lxml==4.9.4
+    # via doxysphinx
+markdown-it-py==2.2.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.5
+    # via jinja2
+mdit-py-plugins==0.3.5
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+mpire==2.10.1
+    # via doxysphinx
+myst-parser==1.0.0
+    # via rocm-docs-core
+packaging==24.0
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+pycparser==2.21
+    # via cffi
+pydata-sphinx-theme==0.14.4
+    # via
+    #   rocm-docs-core
+    #   sphinx-book-theme
+pygithub==2.3.0
+    # via rocm-docs-core
+pygments==2.17.2
+    # via
+    #   accessible-pygments
+    #   mpire
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjson5==1.6.6
+    # via doxysphinx
+pyjwt[crypto]==2.8.0
+    # via
+    #   pygithub
+    #   pyjwt
+pynacl==1.5.0
+    # via pygithub
+pyparsing==3.1.2
+    # via doxysphinx
+pytz==2024.1
+    # via babel
+pyyaml==6.0.1
+    # via
+    #   myst-parser
+    #   rocm-docs-core
+    #   sphinx-external-toc
+requests==2.31.0
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core[api_reference]==0.38.0
+    # via
+    #   -r requirements.in
+    #   rocm-docs-core
+smmap==5.0.1
+    # via gitdb
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.5
+    # via beautifulsoup4
+sphinx==5.3.0
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   rocm-docs-core
+    #   sphinx-book-theme
+    #   sphinx-copybutton
+    #   sphinx-design
+    #   sphinx-external-toc
+    #   sphinx-notfound-page
+sphinx-book-theme==1.0.1
+    # via rocm-docs-core
+sphinx-copybutton==0.5.2
+    # via rocm-docs-core
+sphinx-design==0.5.0
+    # via rocm-docs-core
+sphinx-external-toc==0.3.1
+    # via rocm-docs-core
+sphinx-notfound-page==1.0.0
+    # via rocm-docs-core
+sphinxcontrib-applehelp==1.0.4
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+tqdm==4.66.2
+    # via mpire
+typing-extensions==4.10.0
+    # via
+    #   pydata-sphinx-theme
+    #   pygithub
+urllib3==2.2.1
+    # via
+    #   pygithub
+    #   requests
+wrapt==1.16.0
+    # via deprecated
+zipp==3.18.1
+    # via
+    #   importlib-metadata
+    #   importlib-resources