Documentation update for Read the Docs

Standardize hipSOLVER documentation builds (#149) * Changing Documentation Template - hipSOLVER * hipSOLVER - Version update * hipSOLVER - Deleted runCompileCommand * cleanup and fixes add back build folder to gitignore remove legal disclaimer from index remove rocmlogo * fix typo * Add ./install.sh --docs build option * Cleanup paths * Remove toctree and broken links * Fix typo * Remove table of contents from main page --------- Co-authored-by: Sergey Kostrov <[email protected]> Co-authored-by: Cordell Bloor <[email protected]> Remove old docs system config files (#153) These files will no longer be relevant with the transition to a new docs system in ROCm 5.6. Add dependabot config and pin rocm-docs-core (#155) Bump rocm-docs-core from 0.2.0 to 0.7.1 in /docs/.sphinx (#159) Bumps [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) from 0.2.0 to 0.7.1. - [Release notes](https://github.com/RadeonOpenCompute/rocm-docs-core/releases) - [Changelog](https://github.com/RadeonOpenCompute/rocm-docs-core/blob/develop/CHANGELOG.md) - [Commits](https://github.com/RadeonOpenCompute/rocm-docs-core/commits/v0.7.1) --- updated-dependencies: - dependency-name: rocm-docs-core dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Bump rocm-docs-core from 0.7.1 to 0.8.0 in /docs/.sphinx (#160) Bumps [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) from 0.7.1 to 0.8.0. - [Release notes](https://github.com/RadeonOpenCompute/rocm-docs-core/releases) - [Changelog](https://github.com/RadeonOpenCompute/rocm-docs-core/blob/develop/CHANGELOG.md) - [Commits](ROCm/rocm-docs-core@v0.7.1...v0.8.0) --- updated-dependencies: - dependency-name: rocm-docs-core dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Update documentation requirements (#161) Bump rocm-docs-core from 0.11.0 to 0.13.2 in /docs/.sphinx (#164) Bumps [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) from 0.11.0 to 0.13.2. - [Release notes](https://github.com/RadeonOpenCompute/rocm-docs-core/releases) - [Changelog](https://github.com/RadeonOpenCompute/rocm-docs-core/blob/develop/CHANGELOG.md) - [Commits](ROCm/rocm-docs-core@v0.11.0...v0.13.2) --- updated-dependencies: - dependency-name: rocm-docs-core dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> rocm-docs-core==0.13.4
ROCm · Jun 15, 2023 · f63301e · f63301e
1 parent 9d85697
commit f63301e
Show file tree

Hide file tree

Showing 41 changed files with 299 additions and 683 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,12 @@
+# 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: "/" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
diff --git a/.gitignore b/.gitignore
@@ -33,9 +33,16 @@
 
 # build-in-source directory
 build/
-docBin/
 
 # emacs temporary/backup files
 .\#*
 \#*\#
 *~
+
+# documentation artifacts
+_build/
+_images/
+_static/
+_templates/
+_toc.yml
+docBin/
diff --git a/.jenkins/staticanalysis.groovy b/.jenkins/staticanalysis.groovy
@@ -9,33 +9,6 @@ import com.amd.project.*
 import com.amd.docker.*
 import java.nio.file.Path
 
-def runCompileCommand(platform, project, jobName, boolean debug=false)
-{
-    project.paths.construct_build_prefix()
-
-    def command = """#!/usr/bin/env bash
-            set -x
-            ${project.paths.project_build_prefix}/docs/run_doc.sh
-            """
-
-    try
-    {
-        platform.runCommand(this, command)
-    }
-    catch(e)
-    {
-        throw e
-    }
-
-    publishHTML([allowMissing: false,
-                alwaysLinkToLastBuild: false,
-                keepAll: false,
-                reportDir: "${project.paths.project_build_prefix}/docs/build/html",
-                reportFiles: "index.html",
-                reportName: "Documentation",
-                reportTitles: "Documentation"])
-}
-
 def runCI =
 {
     nodeDetails, jobName->
@@ -48,14 +21,7 @@ def runCI =
     boolean formatCheck = true
     boolean staticAnalysis = true
 
-    def compileCommand =
-    {
-        platform, project->
-
-        runCompileCommand(platform, project, jobName, false)
-    }
-
-    buildProject(prj, formatCheck, nodes.dockerArray, compileCommand, null, null, staticAnalysis)
+    buildProject(prj, formatCheck, nodes.dockerArray, null, null, null, staticAnalysis)
 }
 
 ci: {

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -4,11 +4,11 @@
 version: 2
 
 sphinx:
-   configuration: docs/source/conf.py
+   configuration: docs/conf.py
 
-formats: all
+formats: [htmlzip]
 
 python:
-   version: "3.7"
+   version: "3.8"
    install:
-   - requirements: docs/source/requirements.txt
+   - requirements: docs/.sphinx/requirements.txt
diff --git a/README.md b/README.md
@@ -5,6 +5,18 @@ hipSOLVER is a LAPACK marshalling library, with multiple supported backends.  It
 
 For a detailed description of the hipSOLVER library, its implemented routines, the installation process and user guide, see the [hipSOLVER documentation](https://hipsolver.readthedocs.io/en/latest/).
 
+### How to build documentation
+
+Run the steps below to build documentation locally.
+
+```
+cd docs
+
+pip3 install -r .sphinx/requirements.txt
+
+python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
+```
+
 ## Quickstart Build
 
 To download the hipSOLVER source code, clone this repository with the command:

diff --git a/custom.properties b/custom.properties
diff --git a/docs/Doxyfile → docs/.doxygen/Doxyfile b/docs/Doxyfile → docs/.doxygen/Doxyfile
@@ -46,13 +46,6 @@ PROJECT_NUMBER         = v0.1
 
 PROJECT_BRIEF          = "ROCm SOLVER marshalling library"
 
-# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
-# in the documentation. The maximum height of the logo should not exceed 55
-# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
-# the logo to the output directory.
-
-PROJECT_LOGO           = ./rocmlogo.png
-
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
 # entered, it will be relative to the location where doxygen was started. If
@@ -775,8 +768,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../library/include \
-                         ../library/include/internal
+INPUT                  = ../../library/include \
+                         ../../library/include/internal
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in
@@ -0,0 +1,28 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+root: index
+subtrees:
+  - numbered: False
+    entries:
+    - file: userguide/index
+      subtrees:
+      - entries:
+        - file: userguide/intro
+        - file: userguide/install
+        - file: userguide/usage
+    - file: api/index
+      subtrees:
+      - entries:
+        - file: api/types
+        - file: api/helpers
+        - file: api/auxiliary
+        - file: api/lapack
+        - file: api/lapacklike
+    - file: compat-api/index
+      subtrees:
+      - entries:
+        - file: compat-api/types
+        - file: compat-api/helpers
+        - file: compat-api/auxiliary
+        - file: compat-api/lapack
+        - file: compat-api/lapacklike
diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in
@@ -0,0 +1 @@
+rocm-docs-core==0.13.4
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
@@ -0,0 +1,155 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+accessible-pygments==0.0.3
+    # via pydata-sphinx-theme
+alabaster==0.7.13
+    # via sphinx
+babel==2.12.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.11.2
+    # via pydata-sphinx-theme
+breathe==4.34.0
+    # via rocm-docs-core
+certifi==2022.12.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==40.0.2
+    # via pyjwt
+deprecated==1.2.13
+    # via pygithub
+docutils==0.19
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+fastjsonschema==2.16.3
+    # 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.2
+    # 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.0
+    # 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.1
+    # via rocm-docs-core
+pygments==2.14.0
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt[crypto]==2.6.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.28.2
+    # 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
+    # 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.1
+    # 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.5.0
+    # via pydata-sphinx-theme
+uc-micro-py==1.0.1
+    # via linkify-it-py
+urllib3==1.26.15
+    # via requests
+wrapt==1.15.0
+    # via deprecated
+zipp==3.15.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources
diff --git a/docs/Dockerfile b/docs/Dockerfile
@@ -0,0 +1,6 @@
+FROM readthedocs/build:latest
+
+USER root:root
+COPY .sphinx/requirements.txt requirements.txt
+RUN pip3 install -r requirements.txt
+RUN rm requirements.txt
diff --git a/docs/source/api_auxiliaryfunc.rst → docs/api/auxiliary.rst b/docs/source/api_auxiliaryfunc.rst → docs/api/auxiliary.rst
diff --git a/docs/source/api_helperfunc.rst → docs/api/helpers.rst b/docs/source/api_helperfunc.rst → docs/api/helpers.rst