Documentation updates for Read the Docs

Docsupdate (#1748)
Co-authored-by: Sam Wu <sam.wu2@amd.com>
Co-authored-by: Paul <pfultz2@yahoo.com>

rocm-docs-core v0.13.4

fix licensing for actions

.dockerignore

+# Ignore everything
+**
+
+# Allow files and directories
+!*.txt
+!*.ini
+!/tools/*.sh
+!/test/onnx/.onnxrt-commit
+!/docs/.sphinx/*.txt

.github/dependabot.yml

+# 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
+    schedule:
+      interval: "daily"
+  - package-ecosystem: "pip"
+    directory: "/tools/accuracy"
+    schedule:
+      interval: "daily"
+  - package-ecosystem: "pip"
+    directory: "/examples/vision/python_unet"
+    schedule:
+      interval: "daily"
+  - package-ecosystem: "pip"
+    directory: "/examples/vision/python_super_resolution"
+    schedule:
+      interval: "daily"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/ci.yaml

@@ -155,7 +155,7 @@ jobs:
     - name: Run pyflakes
       run: |
         pyflakes --version
-        pyflakes examples/ tools/ src/ test/ doc/
+        pyflakes examples/ tools/ src/ test/ docs/
         mypy --version
         mypy tools/api.py
 

.github/workflows/sync-onnxrt-main.yaml

+name: Onnxruntime main weekly sync
+
+on:
+  schedule:
+    - cron: '07 17 * * 5'
+
+jobs:
+  createPullRequest:
+    name: Update and create pull request
+    runs-on: ubuntu-latest
+    steps:
+      - name: get_date
+        run: echo todays_date="$(date +'%Y-%m-%d')" >> $GITHUB_ENV
+
+      - name: extract_sha1 
+        run: echo onnxsha="$(git ls-remote https://github.com/microsoft/onnxruntime.git HEAD | awk '{print $1}')" >> $GITHUB_ENV
+
+      - name: echo_sha1
+        run: echo ${{ env.onnxsha }}
+
+      - uses: actions/checkout@v3
+        with: 
+          ref: develop
+
+      - name: update_file
+        run:  echo ${{ env.onnxsha }} > test/onnx/.onnxrt-commit
+
+      - name: Make changes to pull request
+        uses: peter-evans/create-pull-request@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: Update onnxruntime main ${{ env.onnxsha }}
+          committer: Github <noreply@github.com>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          signoff: false
+          branch: onnxruntime-sync-${{ env.todays_date }}
+          delete-branch: true
+          title: 'Onnxruntime Weekly Sync ${{ env.todays_date }}'
+          body: |
+            Update CI point for Onnxruntime builds
+            - Updated with changes from ${{ env.todays_date }}
+            - Auto-generated by [create-pull-request][1]
+            - Update .onnxrt-commit to ${{ env.onnxsha }}
+
+            [1]: https://github.com/peter-evans/create-pull-request
+          labels: |
+            onnxruntime
+            dependancies
+            automated 
+          assignees: TedThemistokleous
+          reviewers: TedThemistokleous causten
+          draft: false
+          base: develop

.gitignore

@@ -48,6 +48,8 @@
 
 /CMakeSettings.json
 
+# documentation artifacts
+_toc.yml
 
 #==============================================================================#
 # Directories to ignore (do not add trailing '/'s, they skip symlinks).
@@ -61,3 +63,12 @@ test/onnx/models
 # VS2017 and VSCode config files.
 .vscode
 .vs
+
+# documentation artifacts
+docs/_build
+docs/_images
+docs/_static
+docs/_templates
+docs/.doxygen/docBin
+docs/_doxygen
+/_readthedocs

.readthedocs.yaml

+# 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]
+
+python:
+   version: "3.8"
+   install:
+   - requirements: docs/.sphinx/requirements.txt

CHANGELOG.md

+# Change Log for MIGraphX
+
+Full documentation for MIGraphX is available at [MIGraphX Documentation](https://rocmdocs.amd.com/projects/AMDMIGraphX/en/latest/).
+
+## MIGraphX 2.5 for ROCm 5.5.0
+
+### Added
+- Y-Model feature to store tuning information with the optimized model
+- Added Python 3.10 bindings 
+- Accuracy checker tool based on ONNX Runtime
+- ONNX Operators parse_split, and Trilu 
+- Build support for ROCm MLIR
+- Added migraphx-driver flag to print optimizations in python (--python)
+- Added JIT implementation of the Gather and Pad operator which results in better handling of larger tensor sizes.
+
+
+### Optimizations
+- Improved performance of Transformer based models
+- Improved performance of the Pad, Concat, Gather, and Pointwise operators
+- Improved onnx/pb file loading speed
+- Added general optimize pass which runs several passes such as simplify_reshapes/algebra and DCE in loop.
+
+
+### Fixed
+- Improved parsing Tensorflow Protobuf files 
+- Resolved various accuracy issues with some onnx models
+- Resolved a gcc-12 issue with mivisionx
+- Improved support for larger sized models and batches
+- Use --offload-arch instead of --cuda-gpu-arch for the HIP compiler
+- Changes inside JIT to use float accumulator for large reduce ops of half type to avoid overflow.
+- Changes inside JIT to temporarily use cosine to compute sine function.
+
+### Changed
+- Changed version/location of 3rd party build dependencies to pick up fixes

CMakeLists.txt

@@ -234,7 +234,7 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/bin)
 add_subdirectory(src)
-add_subdirectory(doc)
+add_subdirectory(docs)
 add_subdirectory(test)
 add_subdirectory(tools)
 

Dockerfile

@@ -65,7 +65,7 @@ RUN test -f /usr/local/hash || exit 1
 RUN pip3 install yapf==0.28.0
 
 # Install doc requirements
-ADD doc/requirements.txt /doc-requirements.txt
+ADD docs/.sphinx/requirements.txt /doc-requirements.txt
 RUN pip3 install -r /doc-requirements.txt
 
 # Download real models to run onnx unit tests
@@ -100,4 +100,3 @@ ENV LD_LIBRARY_PATH=$PREFIX/lib
 ENV UBSAN_OPTIONS=print_stacktrace=1
 ENV ASAN_OPTIONS=detect_stack_use_after_return=1:check_initialization_order=1:strict_init_order=1
 RUN ln -s /opt/rocm/llvm/bin/llvm-symbolizer /usr/bin/llvm-symbolizer
-

Jenkinsfile

@@ -22,6 +22,7 @@ def rocmtestnode(Map conf) {
             cd build
             CXX=${compiler} CXXFLAGS='-Werror' cmake -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache ${flags} ..
             make -j\$(nproc) generate all doc package check VERBOSE=1
+            md5sum ./*.deb
         """
         echo cmd
         sh cmd
@@ -131,7 +132,8 @@ rocmtest onnx: onnxnode('rocmtest') { cmake_build ->
     stage("Onnx runtime") {
         sh '''
             apt install half
-            ls -lR
+            #ls -lR
+            md5sum ./build/*.deb
             dpkg -i ./build/*.deb
             cd /onnxruntime && ./build_and_test_onnxrt.sh
         '''

README.md

@@ -190,13 +190,19 @@ HTML and PDF documentation can be built using:
 
 `cmake --build . --config Release --target doc` **OR** `make doc`
 
-This will build a local searchable web site inside the doc/html folder.
+This will build a local searchable web site inside the docs/html folder.
 
-Documentation is built using [Doxygen](http://www.stack.nl/~dimitri/doxygen/download.html), [Sphinx](http://www.sphinx-doc.org/en/stable/index.html), and [Breathe](https://breathe.readthedocs.io/en/latest/)
+Documentation is built using [Doxygen](http://www.stack.nl/~dimitri/doxygen/download.html) and [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core)
 
-Requirements for both Sphinx and Breathe can be installed with:
+Run the steps below to build documentation locally.
 
-`pip install -r doc/requirements.txt`
+```
+cd docs
+
+pip3 install -r .sphinx/requirements.txt
+
+python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
+```
 
 Depending on your setup `sudo` may be required for the pip install.
 

doc/requirements.txt

-docutils==0.17.1
-sphinx==4.2.0
-breathe==4.31.0
-sphinx_rtd_theme==1.0.0
-# git+https://github.com/arximboldi/breathe@fix-node-parent

docs/.doxygen/Doxyfile

+# Auto-generated doxygen configuration file
+
+BUILTIN_STL_SUPPORT = YES
+
+CALLER_GRAPH = YES
+
+CALL_GRAPH = YES
+
+ENUM_VALUES_PER_LINE = 1
+
+EXCLUDE_PATTERNS = ../../src/targets/gpu/kernels ../../src/targets/gpu/device
+
+EXTRACT_ALL = YES
+
+FULL_PATH_NAMES = YES
+
+GENERATE_LATEX = NO
+
+GENERATE_TREEVIEW = YES
+
+GENERATE_XML = YES
+
+INCLUDE_PATH = ../../src/include ../../src/targets/cpu/include ../../src/targets/gpu/include
+
+INPUT = ../../src
+
+MACRO_EXPANSION = YES
+
+OUTPUT_DIRECTORY = docBin
+
+PREDEFINED = DOXYGEN
+
+PROJECT_NAME = MIGraphX
+
+RECURSIVE = YES
+
+REFERENCED_BY_RELATION = YES
+
+REFERENCES_LINK_SOURCE = YES
+
+REFERENCES_RELATION = YES
+
+SEARCH_INCLUDES = YES
+
+SORT_MEMBERS_CTORS_1ST = YES
+
+SOURCE_BROWSER = YES
+
+STRIP_FROM_INC_PATH = ../../src/include ../../src/targets/cpu/include ../../src/targets/gpu/include
+
+STRIP_FROM_PATH = 
+
+USE_PDFLATEX = NO
+
+WARN_LOGFILE = DoxygenWarningLog.txt
+
+DOT_PATH = 
+
+HAVE_DOT = NO

docs/.sphinx/_toc.yml.in

+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+root: index
+subtrees:
+  - numbered: False
+    entries:
+    - file: py_user_guide
+    - file: cpp_user_guide
+    - file: driver
+    - file: contributor_guide

docs/.sphinx/requirements.in

+rocm-docs-core==0.13.4

docs/.sphinx/requirements.txt

+#####################################################################################
+# The MIT License (MIT)
+#
+# Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#####################################################################################
+
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+accessible-pygments==0.0.4
+    # via pydata-sphinx-theme
+alabaster==0.7.13
+    # via sphinx
+babel==2.12.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.12.2
+    # via pydata-sphinx-theme
+breathe==4.35.0
+    # via rocm-docs-core
+certifi==2023.5.7
+    # via requests
+cffi==1.15.1
+    # via
+    #   cryptography
+    #   pynacl
+charset-normalizer==3.1.0
+    # via requests
+click==8.1.3
+    # via sphinx-external-toc
+cryptography==41.0.1
+    # via pyjwt
+deprecated==1.2.14
+    # via pygithub
+docutils==0.19
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+fastjsonschema==2.17.1
+    # via rocm-docs-core
+gitdb==4.0.10
+    # via gitpython
+gitpython==3.1.31
+    # via rocm-docs-core
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==6.6.0
+    # via sphinx
+importlib-resources==5.12.0
+    # via rocm-docs-core
+jinja2==3.1.2
+    # via
+    #   myst-parser
+    #   sphinx
+linkify-it-py==1.0.3
+    # via myst-parser
+markdown-it-py==2.2.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.3
+    # via jinja2
+mdit-py-plugins==0.3.5
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser[linkify]==1.0.0
+    # via rocm-docs-core
+packaging==23.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+pycparser==2.21
+    # via cffi
+pydata-sphinx-theme==0.13.3
+    # via
+    #   rocm-docs-core
+    #   sphinx-book-theme
+pygithub==1.58.2
+    # via rocm-docs-core
+pygments==2.15.1
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt[crypto]==2.7.0
+    # via pygithub
+pynacl==1.5.0
+    # via pygithub
+pytz==2023.3
+    # via babel
+pyyaml==6.0
+    # via
+    #   myst-parser
+    #   rocm-docs-core
+    #   sphinx-external-toc
+requests==2.31.0
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core==0.13.4
+    # via -r requirements.in
+smmap==5.0.0
+    # via gitdb
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.4.1
+    # 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.4.1
+    # via rocm-docs-core
+sphinx-external-toc==0.3.1
+    # via rocm-docs-core
+sphinx-notfound-page==0.8.3
+    # 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
+typing-extensions==4.6.3
+    # via pydata-sphinx-theme
+uc-micro-py==1.0.2
+    # via linkify-it-py
+urllib3==2.0.3
+    # via requests
+wrapt==1.15.0
+    # via deprecated
+zipp==3.15.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources

docs/CMakeLists.txt

+#####################################################################################
+# The MIT License (MIT)
+#
+# Copyright (c) 2015-2022 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#####################################################################################
+project(migraphx-doc)
+find_package(ROCM REQUIRED)
+
+include(ROCMSphinxDoc)
+rocm_add_sphinx_doc(
+    .
+    BUILDER html 
+    OUTPUT_DIR html
+)

docs/conf.py

+# Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved.
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+# 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
+
+from rocm_docs import ROCmDocs
+
+html_output_directory = "../_readthedocs/html"
+setting_all_article_info = True
+all_article_info_os = ["linux"]
+
+docs_core = ROCmDocs("AMD MIGraphX Documentation")
+docs_core.run_doxygen()
+docs_core.setup()
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)