diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..ada22f1b --- /dev/null +++ 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 deleted file mode 100644 index 6311a353..00000000 --- a/.github/workflows/docs.yaml +++ /dev/null @@ -1,58 +0,0 @@ -name: Upload to the upload server - -# Controls when the workflow will run -on: - push: - branches: [develop, master] - tags: - - rocm-5.* - release: - types: [published] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# A workflow run is made up of one or more jobs that can run sequentially or in parallel -jobs: - # This workflow contains a single job called "build" - build: - # The type of runner that the job will run on - runs-on: ubuntu-latest - - # Steps represent a sequence of tasks that will be executed as part of the job - steps: - # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - - uses: actions/checkout@v2 - - - name: getting branch name - shell: bash - run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})" - id: branch_name - - name: getting tag name - shell: bash - run: echo "##[set-output name=tag;]$(echo ${GITHUB_REF_NAME})" - id: tag_name - - name: zipping files - run: zip -r ${{ github.event.repository.name }}_${{ steps.tag_name.outputs.tag }}.zip . -x '*.git*' '*.idea*' - - name: echo-step - run: echo "${{ github.event.release.target_commitish }}" - - name: uploading archive to prod - if: ${{ steps.branch_name.outputs.branch == 'master' || github.event.release.target_commitish == 'master'}} - uses: wlixcc/SFTP-Deploy-Action@v1.0 - with: - username: ${{ secrets.USERNAME }} - server: ${{ secrets.SERVER }} - ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }} - local_path: ${{ github.event.repository.name }}_${{ steps.tag_name.outputs.tag }}.zip - remote_path: '${{ secrets.PROD_UPLOAD_URL }}' - args: '-o ConnectTimeout=5' - - name: uploading archive to staging - if: ${{ steps.branch_name.outputs.branch == 'develop' || github.event.release.target_commitish == 'develop' }} - uses: wlixcc/SFTP-Deploy-Action@v1.0 - with: - username: ${{ secrets.USERNAME }} - server: ${{ secrets.SERVER }} - ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }} - local_path: ${{ github.event.repository.name }}_${{ steps.tag_name.outputs.tag }}.zip - remote_path: '${{ secrets.STG_UPLOAD_URL }}' - args: '-o ConnectTimeout=5' diff --git a/.gitignore b/.gitignore index 423344f0..fa3ef52e 100644 --- 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 index 5defd084..024cbdd1 100644 --- 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 index 66113b9c..43a0890c 100644 --- 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 index d601569b..3e2803fb 100644 --- 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 deleted file mode 100644 index 27702919..00000000 --- a/custom.properties +++ /dev/null @@ -1,3 +0,0 @@ -booktitle=hipSOLVER API Guide -spreadsheet.xml=docs/classification-map.xml -document.locale=enus \ No newline at end of file diff --git a/docs/Doxyfile b/docs/.doxygen/Doxyfile similarity index 99% rename from docs/Doxyfile rename to docs/.doxygen/Doxyfile index 463d3cba..5bad0daa 100644 --- a/docs/Doxyfile +++ b/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 new file mode 100644 index 00000000..46436f3e --- /dev/null +++ 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 new file mode 100644 index 00000000..7f2c40a8 --- /dev/null +++ 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 new file mode 100644 index 00000000..210c72dc --- /dev/null +++ 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 new file mode 100644 index 00000000..f75a3279 --- /dev/null +++ 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 b/docs/api/auxiliary.rst similarity index 100% rename from docs/source/api_auxiliaryfunc.rst rename to docs/api/auxiliary.rst diff --git a/docs/source/api_helperfunc.rst b/docs/api/helpers.rst similarity index 100% rename from docs/source/api_helperfunc.rst rename to docs/api/helpers.rst diff --git a/docs/source/api_index.rst b/docs/api/index.rst similarity index 60% rename from docs/source/api_index.rst rename to docs/api/index.rst index dc50ce24..2834ffe3 100644 --- a/docs/source/api_index.rst +++ b/docs/api/index.rst @@ -6,21 +6,13 @@ hipSOLVER API Currently, this API document only provides the method signatures for the wrapper functions that are currently implemented in hipSOLVER. For a complete description of the functions' behavior and arguments, see the corresponding backends' documentation -at `cuSOLVER API `_ and/or `rocSOLVER API `_. +at `cuSOLVER API `_ and/or `rocSOLVER API `_. The hipSOLVER API is designed to be similar to the cusolverDn and rocSOLVER interfaces, but it requires some minor adjustments to ensure the best performance out of both backends. Generally, this involves the addition of workspace parameters and some additional API methods. -Please refer to the user guide for a complete listing of :ref:`these API adjustments `. +Please refer to the user guide for a complete listing of :ref:`API differences `. Users interested in using hipSOLVER without these adjustments, so that the interface matches cuSOLVER, should instead consult the -:ref:`compatibility API documentation `. See also :ref:`this section ` for more details. - -.. toctree:: - :maxdepth: 5 - - api_types - api_helperfunc - api_auxiliaryfunc - api_lapackfunc - api_lapacklike +:ref:`Compatibility API documentation `. See also :ref:`the porting section ` for more details. +.. tableofcontents:: diff --git a/docs/source/api_lapackfunc.rst b/docs/api/lapack.rst similarity index 100% rename from docs/source/api_lapackfunc.rst rename to docs/api/lapack.rst diff --git a/docs/source/api_lapacklike.rst b/docs/api/lapacklike.rst similarity index 100% rename from docs/source/api_lapacklike.rst rename to docs/api/lapacklike.rst diff --git a/docs/source/api_types.rst b/docs/api/types.rst similarity index 100% rename from docs/source/api_types.rst rename to docs/api/types.rst diff --git a/docs/classification-map.xml b/docs/classification-map.xml deleted file mode 100644 index 66f48ad9..00000000 --- a/docs/classification-map.xml +++ /dev/null @@ -1,189 +0,0 @@ - - - - - Kanika Yadav (external) - Microsoft Office User - 2020-09-25T06:54:04Z - 2021-12-22T19:07:50Z - 16.00 - - - true - 2021-02-23T09:13:03Z - Standard - 90c2fedb-0da6-4717-8531-d16a1b9930f4 - 45597f60-6e37-4be7-acfb-4c9e23b261ea - - 0 - true - 2022-01-14T16:33:39Z - Privileged - AMD Official Use Only-AIP 2.0 - 3dd8961f-e488-4e60-8e11-a82d994e183d - 3ab6c0f7-c658-4f6f-bd9d-6ef921551ff7 - 1 - - - - - - 14235 - 32767 - 32767 - 32767 - False - False - - - - - - - - - - - - - - - - - Filename - Title - Categories - Version - Doc Type - - - MAP - rocm;hip-sdk;hip;gpu;amd;hipsolver;solver - 4-5 - - - apply-ALL - - - default - - - hipSOLVER API Guide - - reference - - - - - - - - - - - - - - - - - - - -
- - -
-