├── .devcontainer ├── Dockerfile └── devcontainer.json ├── .dockerignore ├── .gitattributes ├── .github ├── CODEOWNERS ├── dependabot.yml └── workflows │ ├── linting.yml │ ├── pull_request.yml │ ├── release.yml │ ├── sync_branches.yml │ ├── version-bump.yml │ └── yaml_merger.py ├── .gitignore ├── .gitpod.yml ├── .markdownlint-cli2.yaml ├── .markdownlint.yaml ├── .pre-commit-config.yaml ├── .readthedocs.yaml ├── .spellcheck.local.yaml ├── .spellcheck.yaml ├── .vscode ├── settings.json └── tasks.json ├── .wordlist.txt ├── CHANGELOG.md ├── LICENSE.txt ├── README.md ├── docs ├── .gitignore ├── building_documentation.md ├── conf.py ├── data │ └── commit-status.png ├── demo │ ├── doxygen │ │ ├── .gitignore │ │ └── Doxyfile │ └── sources │ │ ├── example.hpp │ │ └── example1.hpp ├── developer_guide │ ├── commitizen.md │ ├── dependabot.md │ ├── developer_guide.md │ ├── just.md │ ├── projects_yaml.md │ └── python_linting.md ├── index.md ├── license.md ├── sphinx │ ├── .gitignore │ └── _toc.yml.in ├── toolchain.md └── user_guide │ ├── article_info.md │ ├── doxygen_integration.md │ ├── linking.md │ ├── linking_md.md │ ├── linking_rst.rst │ ├── linking_toc.md │ ├── linting.md │ ├── spellcheck.md │ └── user_guide.md ├── justfile ├── pyproject.toml ├── requirements.txt ├── src └── rocm_docs │ ├── __init__.py │ ├── article_info.py │ ├── core.py │ ├── data │ ├── _doxygen │ │ ├── extra_stylesheet.css │ │ ├── footer.html │ │ ├── header.html │ │ └── stylesheet.css │ ├── projects.schema.json │ └── projects.yaml │ ├── doxygen.py │ ├── formatting.py │ ├── projects.py │ ├── py.typed │ ├── rocm_docs_theme │ ├── 404.html │ ├── components │ │ ├── article-info.html │ │ ├── left-side-menu.html │ │ └── toggle-primary-sidebar.html │ ├── flavors │ │ ├── ai-developer-hub │ │ │ ├── footer.jinja │ │ │ ├── header.jinja │ │ │ └── left-side-menu.jinja │ │ ├── generic │ │ │ ├── footer.jinja │ │ │ ├── header.jinja │ │ │ └── left-side-menu.jinja │ │ ├── instinct │ │ │ ├── footer.jinja │ │ │ ├── header.jinja │ │ │ └── left-side-menu.jinja │ │ ├── rocm-blogs │ │ │ ├── footer.jinja │ │ │ ├── header.jinja │ │ │ └── left-side-menu.jinja │ │ ├── rocm-docs-home │ │ │ ├── footer.jinja │ │ │ ├── header.jinja │ │ │ └── left-side-menu.jinja │ │ ├── rocm-ds │ │ │ ├── footer.jinja │ │ │ ├── header.jinja │ │ │ └── left-side-menu.jinja │ │ └── rocm │ │ │ ├── footer.jinja │ │ │ ├── header.jinja │ │ │ ├── left-side-menu.jinja │ │ │ └── meta.jinja │ ├── layout.html │ ├── sections │ │ ├── footer-content.html │ │ ├── footer.html │ │ ├── header.html │ │ └── meta.html │ ├── static │ │ ├── code_word_breaks.js │ │ ├── custom.css │ │ ├── fonts.css │ │ ├── fonts.css.map │ │ ├── fonts.scss │ │ ├── fonts │ │ │ └── open-sans │ │ │ │ ├── open-sans-v34-latin-300.woff │ │ │ │ ├── open-sans-v34-latin-300.woff2 │ │ │ │ ├── open-sans-v34-latin-300italic.woff │ │ │ │ ├── open-sans-v34-latin-300italic.woff2 │ │ │ │ ├── open-sans-v34-latin-500.woff │ │ │ │ ├── open-sans-v34-latin-500.woff2 │ │ │ │ ├── open-sans-v34-latin-500italic.woff │ │ │ │ ├── open-sans-v34-latin-500italic.woff2 │ │ │ │ ├── open-sans-v34-latin-600.woff │ │ │ │ ├── open-sans-v34-latin-600.woff2 │ │ │ │ ├── open-sans-v34-latin-600italic.woff │ │ │ │ ├── open-sans-v34-latin-600italic.woff2 │ │ │ │ ├── open-sans-v34-latin-700.woff │ │ │ │ ├── open-sans-v34-latin-700.woff2 │ │ │ │ ├── open-sans-v34-latin-700italic.woff │ │ │ │ ├── open-sans-v34-latin-700italic.woff2 │ │ │ │ ├── open-sans-v34-latin-800.woff │ │ │ │ ├── open-sans-v34-latin-800.woff2 │ │ │ │ ├── open-sans-v34-latin-800italic.woff │ │ │ │ ├── open-sans-v34-latin-800italic.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-300.woff │ │ │ │ ├── open-sans-v34-latin-ext-300.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-300italic.woff │ │ │ │ ├── open-sans-v34-latin-ext-300italic.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-500.woff │ │ │ │ ├── open-sans-v34-latin-ext-500.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-500italic.woff │ │ │ │ ├── open-sans-v34-latin-ext-500italic.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-600.woff │ │ │ │ ├── open-sans-v34-latin-ext-600.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-600italic.woff │ │ │ │ ├── open-sans-v34-latin-ext-600italic.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-700.woff │ │ │ │ ├── open-sans-v34-latin-ext-700.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-700italic.woff │ │ │ │ ├── open-sans-v34-latin-ext-700italic.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-800.woff │ │ │ │ ├── open-sans-v34-latin-ext-800.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-800italic.woff │ │ │ │ ├── open-sans-v34-latin-ext-800italic.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-italic.woff │ │ │ │ ├── open-sans-v34-latin-ext-italic.woff2 │ │ │ │ ├── open-sans-v34-latin-ext-regular.woff │ │ │ │ ├── open-sans-v34-latin-ext-regular.woff2 │ │ │ │ ├── open-sans-v34-latin-italic.woff │ │ │ │ ├── open-sans-v34-latin-italic.woff2 │ │ │ │ ├── open-sans-v34-latin-regular.woff │ │ │ │ └── open-sans-v34-latin-regular.woff2 │ │ ├── images │ │ │ ├── alpha-watermark.svg │ │ │ ├── amd-header-logo.svg │ │ │ ├── banner-violet.jpg │ │ │ ├── beta-watermark.svg │ │ │ └── rocm-logo.png │ │ ├── rdcMisc.js │ │ ├── renameVersionLinks.js │ │ ├── rocm_footer.css │ │ ├── rocm_header.css │ │ ├── search.js │ │ └── theme_mode_captions.js │ └── theme.conf │ ├── theme.py │ └── util.py └── tests ├── __init__.py ├── conftest.py ├── log_fixtures.py ├── projects_fixtures.py ├── sites ├── doxygen │ ├── extension │ │ └── conf.py │ └── legacy │ │ └── conf.py ├── pass │ ├── minimal │ │ └── conf.py │ └── minimal_legacy │ │ └── conf.py ├── templates │ ├── doxygen │ │ ├── .doxygen │ │ │ ├── A.cpp │ │ │ └── Doxyfile │ │ ├── .sphinx │ │ │ └── _toc.yml.in │ │ ├── breathe.md │ │ └── doxylink.md │ ├── minimal │ │ ├── .sphinx │ │ │ └── _toc.yml.in │ │ ├── a.md │ │ └── index.md │ └── standard │ │ ├── a.md │ │ ├── index.md │ │ └── sphinx │ │ └── _toc.yml.in └── theme_flavors │ ├── rocm-blogs │ └── conf.py │ ├── rocm-docs-home │ └── conf.py │ └── rocm │ └── conf.py ├── sphinx_fixtures.py ├── test_doxygen.py ├── test_meta.py └── test_projects.py /.devcontainer/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:3.10-bullseye 2 | 3 | ENV LANG=C.UTF-8 \ 4 | LC_ALL=C.UTF-8 5 | 6 | RUN apt-get update && \ 7 | apt-get install -y --no-install-recommends \ 8 | curl \ 9 | doxygen \ 10 | graphviz \ 11 | ssh \ 12 | sudo \ 13 | zsh \ 14 | && rm -rf /var/lib/apt/lists/* 15 | 16 | # Install just 17 | RUN curl --proto '=https' -sSf https://just.systems/install.sh \ 18 | | sudo bash -s -- --tag 1.13.0 --to /usr/local/bin 19 | 20 | # Add the render group and a user with sudo permissions for the container 21 | RUN useradd -Um developer \ 22 | && echo developer ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/developer \ 23 | && chmod 0440 /etc/sudoers.d/developer 24 | 25 | CMD mkdir -p /workspace && chown developer:developer /workspace 26 | 27 | WORKDIR /workspace 28 | VOLUME /workspace 29 | 30 | USER developer 31 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | { 2 | "build": { 3 | "dockerfile": "Dockerfile" 4 | }, 5 | "updateContentCommand": "just devenv docs", 6 | "customizations": { 7 | "vscode": { 8 | "extensions": [ 9 | "ms-python.black-formatter", 10 | "ms-python.python", 11 | "ritwickdey.LiveServer", 12 | "tamasfe.even-better-toml" 13 | ] 14 | } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /.dockerignore: -------------------------------------------------------------------------------- 1 | * 2 | !.devcontainer 3 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Force lf to workaround pre-commit hook limitation 2 | /.wordlist.txt text eol=lf 3 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Documentation files 2 | docs/* @ROCm/rocm-documentation 3 | *.md @ROCm/rocm-documentation 4 | *.rst @ROCm/rocm-documentation 5 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 5 | 6 | version: 2 7 | updates: 8 | - package-ecosystem: "pip" # See documentation for possible values 9 | directory: "/" # Location of package manifests 10 | open-pull-requests-limit: 10 11 | schedule: 12 | interval: "daily" 13 | commit-message: 14 | prefix: "build" 15 | labels: 16 | - "documentation" 17 | - "dependencies" 18 | reviewers: 19 | - "samjwu" 20 | -------------------------------------------------------------------------------- /.github/workflows/linting.yml: -------------------------------------------------------------------------------- 1 | name: Docs Linting 2 | 3 | on: 4 | workflow_call: 5 | push: 6 | branches: [develop, main] 7 | pull_request: 8 | branches: [develop, main] 9 | 10 | concurrency: 11 | group: ${{ github.ref }}-${{ github.workflow }} 12 | cancel-in-progress: true 13 | 14 | jobs: 15 | lint-md: 16 | name: "Markdown" 17 | runs-on: ubuntu-latest 18 | steps: 19 | - name: Checkout code 20 | uses: actions/checkout@v4 21 | - name: Fetch config 22 | shell: sh 23 | run: | 24 | test -f .markdownlint.yaml && echo "Using local config file" || curl --silent --show-error --fail --location https://raw.github.com/ROCm/rocm-docs-core/develop/.markdownlint.yaml -O 25 | - name: Use markdownlint-cli2 26 | uses: DavidAnson/markdownlint-cli2-action@v10.0.1 27 | with: 28 | globs: "**/*.md" 29 | 30 | spelling: 31 | name: "Spelling" 32 | runs-on: ubuntu-latest 33 | steps: 34 | - name: Checkout code 35 | uses: actions/checkout@v4 36 | - name: Fetch config 37 | if: ${{ ! contains( github.repository, 'rocm-docs-core') }} 38 | shell: sh 39 | run: | 40 | curl --silent --show-error --fail --location https://raw.github.com/ROCm/rocm-docs-core/develop/.github/workflows/yaml_merger.py -o .github/workflows/yaml_merger.py 41 | curl --silent --show-error --fail --location https://raw.github.com/ROCm/rocm-docs-core/develop/.spellcheck.yaml -O 42 | curl --silent --show-error --fail --location https://raw.github.com/ROCm/rocm-docs-core/develop/.wordlist.txt >> .wordlist.txt 43 | - name: Check local spelling file 44 | id: check_local_spelling 45 | run: | 46 | if [ -f .spellcheck.local.yaml ]; then 47 | echo "check_result=true" >> $GITHUB_OUTPUT 48 | else 49 | echo "check_result=false" >> $GITHUB_OUTPUT 50 | fi 51 | - name: Merge local and main YAML files 52 | if: steps.check_local_spelling.outputs.check_result == 'true' 53 | shell: sh 54 | run: | 55 | python3 .github/workflows/yaml_merger.py .spellcheck.yaml .spellcheck.local.yaml .spellcheck.yaml 56 | - name: Run spellcheck 57 | uses: rojopolis/spellcheck-github-actions@0.46.0 58 | - name: On fail 59 | if: failure() 60 | run: | 61 | echo "Please check for spelling mistakes or add them to '.wordlist.txt' in either the root of this project or in rocm-docs-core." 62 | -------------------------------------------------------------------------------- /.github/workflows/pull_request.yml: -------------------------------------------------------------------------------- 1 | name: Code 2 | on: 3 | pull_request: 4 | 5 | jobs: 6 | lint: 7 | name: Python Linting 8 | strategy: 9 | matrix: 10 | os: ["ubuntu-latest", "windows-latest"] 11 | python-version: ["3.10"] 12 | 13 | runs-on: ${{ matrix.os }} 14 | steps: 15 | - uses: actions/checkout@v4 16 | with: 17 | fetch-depth: 0 18 | - name: Set up Python 19 | uses: actions/setup-python@v4 20 | with: 21 | python-version: "${{ matrix.python-version }}" 22 | cache: pip 23 | cache-dependency-path: | 24 | pyproject.toml 25 | requirements.txt 26 | - name: Cache venv 27 | uses: actions/cache@v4.2.0 28 | with: 29 | path: .venv 30 | key: venv-${{ matrix.os }}-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml','requirements.txt') }} 31 | - run: echo "PRE_COMMIT_HOME=$Env:GITHUB_WORKSPACE/.cache/pre-commit" >> "$Env:GITHUB_ENV" 32 | if: ${{ startsWith(matrix.os, 'windows') }} 33 | - run: echo "PRE_COMMIT_HOME=$GITHUB_WORKSPACE/.cache/pre-commit" >> "$GITHUB_ENV" 34 | if: ${{ !startsWith(matrix.os, 'windows') }} 35 | - name: Cache pre-commit 36 | uses: actions/cache@v4.2.0 37 | with: 38 | path: ${{ env.PRE_COMMIT_HOME }} 39 | key: pre-commit-${{ matrix.os }}-${{ matrix.python-version }}-${{ hashFiles('.pre-commit-config.yaml') }} 40 | - name: Install just 41 | uses: extractions/setup-just@v1 42 | with: 43 | just-version: '1.13.0' 44 | - name: Create virtual env, install requirements 45 | run: just deps 46 | - name: Check commit messages 47 | run: just _check-commit-range "refs/remotes/origin/${{ github.base_ref }}..HEAD" 48 | - name: Check linting, formatting, types 49 | run: just --set verbose_errors true -- check-codestyle 50 | 51 | test: 52 | name: Python Tests 53 | strategy: 54 | fail-fast: true 55 | matrix: 56 | os: ["ubuntu-latest", "windows-latest"] 57 | python-version: ["3.10"] 58 | 59 | runs-on: ${{ matrix.os }} 60 | steps: 61 | - uses: actions/checkout@v4 62 | with: 63 | fetch-depth: 0 64 | - name: Set up Python 65 | uses: actions/setup-python@v4 66 | with: 67 | python-version: "${{ matrix.python-version }}" 68 | cache: pip 69 | cache-dependency-path: | 70 | pyproject.toml 71 | requirements.txt 72 | - name: Set up Doxygen 73 | uses: ssciwr/doxygen-install@v1.2.0 74 | with: 75 | version: 1.9.8 76 | - name: Set up Graphviz 77 | uses: ts-graphviz/setup-graphviz@v2.0.2 78 | with: 79 | ubuntu-graphviz-version: 2.42.2-9ubuntu0.1 80 | windows-graphviz-version: '9.0.0' 81 | - name: Cache venv 82 | uses: actions/cache@v4.2.0 83 | with: 84 | path: .venv 85 | key: venv-${{ matrix.os }}-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml','requirements.txt') }} 86 | - name: Install just 87 | uses: extractions/setup-just@v1 88 | with: 89 | just-version: '1.13.0' 90 | - name: Create virtual env, install requirements 91 | run: just deps 92 | - name: Install 93 | run: just install 94 | - name: Run tests 95 | run: just test 96 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | 3 | on: 4 | push: 5 | tags: 6 | - v[0-9]+.[0-9]+.[0-9]+* 7 | workflow_call: 8 | inputs: 9 | revision: 10 | required: true 11 | type: string 12 | secrets: 13 | PYPI_TOKEN: 14 | required: true 15 | workflow_dispatch: 16 | 17 | jobs: 18 | build: 19 | strategy: 20 | matrix: 21 | python-version: ["3.10"] 22 | 23 | runs-on: ubuntu-latest 24 | steps: 25 | - uses: actions/checkout@v4 26 | with: 27 | ref: ${{ inputs.revision || github.sha }} 28 | - uses: actions/setup-python@v4 29 | with: 30 | python-version: "${{ matrix.python-version }}" 31 | cache: pip 32 | - name: Build python package 33 | shell: sh 34 | run: | 35 | pip install build==0.10.0 36 | python -m build 37 | - uses: actions/upload-artifact@v4.3.6 38 | with: 39 | name: dist-python${{ matrix.python-version }} 40 | path: dist 41 | 42 | publish: 43 | concurrency: publish 44 | needs: [build] 45 | runs-on: ubuntu-latest 46 | env: 47 | PYTHON_VERSION: "3.10" 48 | steps: 49 | - uses: actions/download-artifact@v4.1.8 50 | with: 51 | name: dist-python${{ env.PYTHON_VERSION }} 52 | path: dist 53 | - uses: pypa/gh-action-pypi-publish@v1.12.4 54 | with: 55 | password: ${{ secrets.PYPI_TOKEN }} 56 | -------------------------------------------------------------------------------- /.github/workflows/sync_branches.yml: -------------------------------------------------------------------------------- 1 | name: "Sync to develop" 2 | 3 | on: 4 | workflow_call: 5 | inputs: 6 | sha: 7 | required: true 8 | type: string 9 | workflow_dispatch: 10 | 11 | jobs: 12 | sync_branches: 13 | runs-on: ubuntu-latest 14 | concurrency: sync_branches 15 | name: Sync the branch with the default branch (develop) 16 | steps: 17 | - name: Push develop forward (ff only) 18 | shell: sh 19 | run: | 20 | REF="refs/heads/${{ github.event.repository.default_branch }}" 21 | gh api "/repos/${{ github.repository }}/git/$REF" \ 22 | --method PATCH \ 23 | --header "Accept: application/vnd.github+json" \ 24 | --header "X-GitHub-Api-Version: 2022-11-28" \ 25 | --raw-field sha='${{ inputs.sha || github.sha }}' \ 26 | --field force=false 27 | env: 28 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 29 | -------------------------------------------------------------------------------- /.github/workflows/version-bump.yml: -------------------------------------------------------------------------------- 1 | name: Version Bump 2 | 3 | on: 4 | push: 5 | branches: 6 | - "main" 7 | workflow_dispatch: 8 | 9 | jobs: 10 | bump-version: 11 | name: "Bump version and create changelog with commitizen" 12 | if: "!startsWith(github.event.head_commit.message, 'bump:')" 13 | concurrency: bump-version 14 | runs-on: ubuntu-latest 15 | env: 16 | PYTHON_VERSION: "3.10" 17 | outputs: 18 | bumped: ${{ steps.cz-bump.outputs.bumped }} 19 | revision: ${{ steps.cz-bump.outputs.revision }} 20 | sha: ${{ steps.cz-bump.outputs.sha }} 21 | steps: 22 | - uses: actions/checkout@v4 23 | with: 24 | fetch-depth: 0 25 | - name: Set up Python 26 | uses: actions/setup-python@v4 27 | with: 28 | python-version: "${{ env.PYTHON_VERSION }}" 29 | cache: pip 30 | cache-dependency-path: | 31 | pyproject.toml 32 | requirements.txt 33 | - name: Set up cache 34 | uses: actions/cache@v4.2.0 35 | with: 36 | path: .venv 37 | key: venv-${{ env.PYTHON_VERSION }}-${{ hashFiles('pyproject.toml','requirements.txt') }} 38 | - name: Create virtual env, install requirements 39 | shell: sh 40 | run: | 41 | python -m venv .venv 42 | . .venv/bin/activate 43 | python -m pip install pip-tools 44 | python -m piptools sync requirements.txt 45 | echo "PATH=$PATH" >> "$GITHUB_ENV" 46 | - name: Bump version and generate changelog 47 | shell: sh 48 | id: cz-bump 49 | run: | 50 | git config --local user.name "github-actions[bot]" 51 | git config --local user.email "github-actions[bot]@users.noreply.github.com" 52 | RESULT=0 53 | # Answer yes if asked if this is the first tag created 54 | cz bump --yes --changelog-to-stdout > body.md || RESULT=$? 55 | if [ "$RESULT" -eq 0 ]; then 56 | echo "bumped=true" >> "$GITHUB_OUTPUT" 57 | echo "revision=v$(cz version --project)" >> "$GITHUB_OUTPUT" 58 | echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT" 59 | # https://commitizen-tools.github.io/commitizen/exit_codes/ 60 | # NoneIncrementExit(21): No need to increment the version number 61 | elif [ "$RESULT" -eq 21 ]; then 62 | echo "bumped=false" >> "$GITHUB_OUTPUT" 63 | else 64 | exit $RESULT 65 | fi 66 | - name: Push changes 67 | if: steps.cz-bump.outputs.bumped == 'true' 68 | shell: sh 69 | run: | 70 | git push --atomic origin "HEAD:${{ github.ref }}" \ 71 | "${{ steps.cz-bump.outputs.revision }}" 72 | - name: Release 73 | if: steps.cz-bump.outputs.bumped == 'true' 74 | uses: softprops/action-gh-release@v0.1.15 75 | with: 76 | body_path: "body.md" 77 | tag_name: ${{ steps.cz-bump.outputs.revision }} 78 | 79 | call-release: 80 | name: Trigger a Release 81 | needs: [bump-version] 82 | if: needs.bump-version.outputs.bumped == 'true' 83 | uses: ./.github/workflows/release.yml 84 | with: 85 | revision: ${{ needs.bump-version.outputs.revision }} 86 | secrets: 87 | PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} 88 | 89 | mark-status-checks: 90 | name: Mark required status checks as succeeded 91 | needs: [bump-version] 92 | runs-on: ubuntu-latest 93 | if: needs.bump-version.outputs.bumped == 'true' 94 | steps: 95 | - shell: sh 96 | run: | 97 | REPO="${{ github.repository }}" 98 | SHA="${{ needs.bump-version.outputs.sha }}" 99 | 100 | printf '%s' "${{ vars.REQUIRED_CHECK_CONTEXTS }}" | \ 101 | while IFS="" read -r CONTEXT; do 102 | # Mark each check as succeeded 103 | gh api "/repos/$REPO/statuses/$SHA" \ 104 | --method POST \ 105 | --header "Accept: application/vnd.github+json" \ 106 | --header "X-GitHub-Api-Version: 2022-11-28" \ 107 | --field state=success \ 108 | --field description='Skipped for version bump commit' \ 109 | --raw-field context="$CONTEXT" 110 | done 111 | env: 112 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 113 | 114 | call-sync-branches: 115 | name: Trigger merge 116 | needs: [bump-version, mark-status-checks] 117 | if: needs.bump-version.outputs.bumped == 'true' 118 | uses: ./.github/workflows/sync_branches.yml 119 | with: 120 | sha: ${{ needs.bump-version.outputs.sha }} 121 | -------------------------------------------------------------------------------- /.github/workflows/yaml_merger.py: -------------------------------------------------------------------------------- 1 | import yaml 2 | from typing import List, Dict, Any 3 | import sys 4 | 5 | class ListFlowStyleRepresenter: 6 | """ 7 | Custom representer to force specific flow style for nested lists 8 | """ 9 | def __init__(self): 10 | self.add_representer() 11 | 12 | def represent_list(self, dumper, data): 13 | # Check if this is a nested list containing strings/patterns 14 | if data and isinstance(data[0], str): 15 | return dumper.represent_sequence('tag:yaml.org,2002:seq', data, flow_style=True) 16 | return dumper.represent_sequence('tag:yaml.org,2002:seq', data, flow_style=False) 17 | 18 | def add_representer(self): 19 | yaml.add_representer(list, self.represent_list) 20 | 21 | def load_yaml(file_path: str) -> Any: 22 | """ 23 | Load YAML file with error handling. 24 | """ 25 | try: 26 | with open(file_path, 'r', encoding='utf-8') as f: 27 | return yaml.safe_load(f) 28 | except yaml.scanner.ScannerError as e: 29 | print(f"\nYAML Syntax Error in {file_path}:") 30 | print(f"Line {e.problem_mark.line + 1}, Column {e.problem_mark.column + 1}") 31 | print(f"Error: {e.problem}") 32 | return None 33 | except Exception as e: 34 | print(f"\nError loading {file_path}:") 35 | print(str(e)) 36 | return None 37 | 38 | def merge_matrix_entries(default_entries: List[Dict], user_entries: List[Dict]) -> List[Dict]: 39 | """ 40 | Merge matrix entries, combining sources only for entries with matching names. 41 | - Skip merging if the 'sources' list in the user entries is empty. 42 | - If the main configuration has an empty 'sources' list, replace it with the user's list. 43 | """ 44 | result = default_entries.copy() 45 | default_map = {entry.get('name'): entry for entry in result} 46 | 47 | for user_entry in user_entries: 48 | user_name = user_entry.get('name') 49 | if user_name and user_name in default_map: 50 | if 'sources' in user_entry: 51 | user_sources = user_entry['sources'] 52 | 53 | # Skip merging if user sources are empty 54 | if not user_sources or all(not source for source in user_sources): 55 | continue 56 | 57 | # Check the main configuration's sources 58 | default_sources = default_map[user_name].get('sources', []) 59 | 60 | # If the main config's sources are empty, replace them 61 | if not default_sources or all(not source for source in default_sources): 62 | default_map[user_name]['sources'] = user_sources 63 | else: 64 | # Otherwise, merge the lists 65 | default_map[user_name]['sources'].extend(user_sources) 66 | 67 | return result 68 | 69 | def merge_configs(default: Any, user: Any) -> Any: 70 | """ 71 | Recursively merge two configurations. 72 | """ 73 | if user is None: 74 | return default 75 | 76 | if isinstance(default, dict) and isinstance(user, dict): 77 | result = default.copy() 78 | for key, value in user.items(): 79 | if key in result: 80 | result[key] = merge_configs(result[key], value) 81 | else: 82 | result[key] = value 83 | return result 84 | 85 | if isinstance(default, list) and isinstance(user, list): 86 | if (len(default) > 0 and isinstance(default[0], dict) and 87 | 'name' in default[0] and 'sources' in default[0]): 88 | return merge_matrix_entries(default, user) 89 | return default + user 90 | 91 | return user 92 | 93 | def save_yaml(data: Dict, file_path: str) -> bool: 94 | """ 95 | Save YAML file with custom formatting. 96 | """ 97 | try: 98 | # Initialize custom representer 99 | ListFlowStyleRepresenter() 100 | 101 | with open(file_path, 'w', encoding='utf-8') as f: 102 | yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True) 103 | return True 104 | except Exception as e: 105 | print(f"\nError saving {file_path}:") 106 | print(str(e)) 107 | return False 108 | 109 | if __name__ == '__main__': 110 | import argparse 111 | 112 | parser = argparse.ArgumentParser(description='Merge spellcheck YAML configurations') 113 | parser.add_argument('template', help='Path to template YAML configuration') 114 | parser.add_argument('local', help='Path to local YAML configuration') 115 | parser.add_argument('output', help='Path to save merged configuration') 116 | 117 | args = parser.parse_args() 118 | 119 | # Load configurations 120 | template_config = load_yaml(args.template) 121 | if template_config is None: 122 | sys.exit(1) 123 | 124 | local_config = load_yaml(args.local) 125 | if local_config is None: 126 | sys.exit(1) 127 | 128 | # Merge configurations 129 | merged_config = merge_configs(template_config, local_config) 130 | 131 | # Save merged configuration 132 | if not save_yaml(merged_config, args.output): 133 | sys.exit(1) 134 | 135 | print(f"\nSuccessfully merged configurations into {args.output}") 136 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.mypy_cache 2 | /.ruff_cache 3 | /.venv 4 | **/__pycache__/**/* 5 | **/*.egg-info/**/* 6 | .sass-cache/* 7 | /build 8 | /dist 9 | -------------------------------------------------------------------------------- /.gitpod.yml: -------------------------------------------------------------------------------- 1 | image: 2 | file: .devcontainer/Dockerfile 3 | 4 | tasks: 5 | - name: Create development environment 6 | init: just devenv docs 7 | 8 | vscode: 9 | extensions: 10 | - ms-python.black-formatter 11 | - ms-python.python 12 | - ritwickdey.LiveServer 13 | - tamasfe.even-better-toml 14 | -------------------------------------------------------------------------------- /.markdownlint-cli2.yaml: -------------------------------------------------------------------------------- 1 | ignores: 2 | - CHANGELOG.md 3 | - "{,docs/}{RELEASE,release}.md" 4 | - tools/autotag/templates/**/*.md 5 | -------------------------------------------------------------------------------- /.markdownlint.yaml: -------------------------------------------------------------------------------- 1 | default: true 2 | MD013: false 3 | MD024: 4 | siblings_only: true 5 | MD026: 6 | punctuation: ".,;:!" 7 | MD029: 8 | style: ordered 9 | MD033: false 10 | MD034: false 11 | MD041: false 12 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | default_language_version: 2 | python: python3.10 3 | 4 | default_install_hook_types: [pre-commit, commit-msg] 5 | default_stages: [commit] 6 | 7 | repos: 8 | - repo: https://github.com/pre-commit/pre-commit-hooks 9 | rev: v4.4.0 10 | hooks: 11 | - id: check-yaml 12 | - id: check-json 13 | - id: check-toml 14 | - id: end-of-file-fixer 15 | - id: file-contents-sorter 16 | files: '^.wordlist.txt$' 17 | args: [--unique] 18 | - id: trailing-whitespace 19 | args: [--markdown-linebreak-ext=md] 20 | 21 | - repo: local 22 | hooks: 23 | - id: mypy 24 | name: mypy 25 | entry: just mypy 26 | types_or: [python, pyi] 27 | language: system 28 | exclude: ^docs/|^tests/(sites|templates) 29 | - id: ruff 30 | name: ruff 31 | entry: just ruff 32 | types_or: [python, pyi] 33 | language: system 34 | exclude: ^docs/|^tests/(sites|templates) 35 | require_serial: true 36 | - id: isort 37 | name: isort 38 | entry: just isort 39 | types_or: [python, pyi] 40 | language: system 41 | - id: format 42 | name: format 43 | entry: just format 44 | types_or: [python, pyi] 45 | language: system 46 | - id: commitizen 47 | name: commitizen 48 | entry: just _check-commit-mesg 49 | stages: [commit-msg] 50 | language: system 51 | - id: pip-compile 52 | name: pip-compile 53 | entry: just lock-deps 54 | files: ^pyproject.toml|requirements.txt$ 55 | pass_filenames: false 56 | language: system 57 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # Read the Docs configuration file 2 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 3 | 4 | version: 2 5 | 6 | sphinx: 7 | configuration: docs/conf.py 8 | 9 | formats: [htmlzip, pdf, epub] 10 | 11 | python: 12 | install: 13 | - method: pip 14 | path: . 15 | extra_requirements: 16 | - "api_reference" 17 | - requirements: requirements.txt 18 | 19 | build: 20 | os: ubuntu-22.04 21 | tools: 22 | python: "3.10" 23 | apt_packages: 24 | - "doxygen" 25 | - "graphviz" # For dot graphs in doxygen 26 | -------------------------------------------------------------------------------- /.spellcheck.local.yaml: -------------------------------------------------------------------------------- 1 | matrix: 2 | - name: Markdown 3 | sources: 4 | - [] 5 | - name: reST 6 | sources: 7 | - [] 8 | - name: Cpp 9 | sources: 10 | - [] 11 | -------------------------------------------------------------------------------- /.spellcheck.yaml: -------------------------------------------------------------------------------- 1 | # BSD 3-Clause License 2 | # 3 | # Copyright (c) 2017-2022, Pytorch contributors 4 | # All rights reserved. 5 | # Modifications Copyright (c) 2023, Advanced Micro Devices, Inc. 6 | # All rights reserved. 7 | # 8 | # Redistribution and use in source and binary forms, with or without 9 | # modification, are permitted provided that the following conditions are met: 10 | # 11 | # * Redistributions of source code must retain the above copyright notice, this 12 | # list of conditions and the following disclaimer. 13 | # 14 | # * Redistributions in binary form must reproduce the above copyright notice, 15 | # this list of conditions and the following disclaimer in the documentation 16 | # and/or other materials provided with the distribution. 17 | # 18 | # * Neither the name of the copyright holder nor the names of its 19 | # contributors may be used to endorse or promote products derived from 20 | # this software without specific prior written permission. 21 | 22 | # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 23 | # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24 | # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 25 | # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 26 | # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27 | # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 28 | # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 29 | # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 30 | # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 | # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 | 33 | matrix: 34 | - name: Markdown 35 | sources: 36 | - ['docs/**/*.md'] 37 | expect_match: false 38 | aspell: 39 | lang: en 40 | dictionary: 41 | wordlists: 42 | - .wordlist.txt 43 | pipeline: 44 | - pyspelling.filters.context: 45 | context_visible_first: true 46 | delimiters: 47 | # Manual disabling via: #spellcheck-disable 48 | - open : '^ *$' 49 | content: '[\s\S]*?' 50 | close: '^ *$' 51 | # Ignore URLs in [text](URL) 52 | - open : '\[[^]]*?]\(' 53 | content: '[^)]*?' 54 | close: '\)' 55 | # Ignore out-of-line URL references in [text][reference-name] 56 | - open : '\[[^\]]*?\]\[' 57 | content: '[^\]]*?' 58 | close: '\]' 59 | # Ignore out-of-line URL definitions 60 | - open : '^ {0,3}\[[^\]]*?\]:\s*\S+' 61 | close: '$' 62 | # Ignore URLs in 63 | - open : '\<' 64 | content: '[^]]*?' 65 | close: '\>' 66 | # Ignore text in backtick code blocks. 67 | - open : '(?s)^(?P *`{3,})[^\n]*$' 68 | close: '^(?P=open)$' 69 | # Ignore text between inline back ticks 70 | - open : '(?P`+)' 71 | content: '[^\n]+' 72 | close: '(?P=open)' 73 | # Ignore block classes and extra in :::{class} extra 74 | - open : '^ *:{3,}' 75 | content: '[^\n]+' 76 | close: '' 77 | # Ignore keys in :property: key 78 | - open : '^ *:[^\n:]*: +' 79 | content: '[^\n]+' 80 | close: '$' 81 | # Ignore properties in :property: 82 | - open : '^ *:' 83 | close: ':' 84 | # Ignore tag in (tag)= 85 | - open : '(' 86 | content: '[^\n]+' 87 | close: ')=$' 88 | - pyspelling.filters.url: 89 | - name: reST 90 | sources: 91 | - ['docs/**/*.rst'] 92 | expect_match: false 93 | aspell: 94 | lang: en 95 | dictionary: 96 | wordlists: 97 | - .wordlist.txt 98 | pipeline: 99 | - pyspelling.filters.text: 100 | - pyspelling.filters.context: 101 | context_visible_first: true 102 | delimiters: 103 | # Ignore possessive endings 104 | - open: '(?<=\w)''s(?!\w)' 105 | close: '\b' 106 | # Ignore text between inline back ticks 107 | - open: '(div style|iframe).*' 108 | close: '\n' 109 | - open: '(- )?(?P`+)' 110 | close: '(?P=open)' 111 | # Ignore reStructuredText roles 112 | - open: ':(?:(class|file|func|math|ref|octicon|meth|obj)):`' 113 | content: '[^`]*' 114 | close: '`' 115 | - open: ':width:' 116 | close: '$' 117 | # Exclude raw directive 118 | - open: '\.\. (raw|grid-item-card|galleryitem|includenodoc)::.*$\n*' 119 | close: '\n' 120 | # Ignore reStructuredText literals 121 | - open: '::$' 122 | close: '(?P(?:((?P[ ]+).*$)|(\n))+)' 123 | # Ignore reStructuredText hyperlinks 124 | - open: '\s' 125 | content: '\w*' 126 | close: '_' 127 | # Ignore reStructuredText header --- 128 | - open: '^' 129 | content: '--*' 130 | close: '$' 131 | # Ignore reStructuredText header ''' 132 | - open: '^' 133 | content: '''''*' 134 | close: '$' 135 | # Ignore reStructuredText block directives 136 | - open: '\.\. (code-block|math|csv-table)::.*$\n*' 137 | content: '(?P(^(?P[ ]+).*$\n))(?P(^([ \t]+.*|[ \t]*)$\n)*)' 138 | close: '(^(?![ \t]+.*$))' 139 | - open: '\.\. (raw)::.*$\n*' 140 | close: '^\s*$' 141 | # Ignore reStructuredText substitution definitions 142 | - open: '^\.\. \|[^|]+\|' 143 | close: '$' 144 | # Ignore reStructuredText substitutions 145 | - open: '\|' 146 | content: '[^|]*' 147 | close: '\|_?' 148 | # Ignore reStructuredText toctree 149 | - open: '\.\.\s+toctree::' 150 | close: '(?P(?:((?P[ ]+).*$)|(\n))+)' 151 | # Ignore directives 152 | - open: '\.\.\s+(figure|image|include|only|tabularcolumns|datatemplate:nodata)::' 153 | close: '$' 154 | # Ignore reStructuredText reference 155 | - open: '^.{2}[ ]+_' 156 | close: '$' 157 | # Ignore doxygen directives 158 | - open: '\.\. (autodoxygenindex|doxygenfunction|doxygenstruct|doxygenclass|doxygennamespace|doxygenconcept|doxygenenum|doxygenenumvalue|doxygentypedef|doxygenunion|doxygendefine|doxygenvariable|doxygenfile|doxygengroup|autodoxygenfile|doxygenpage)::.*$\n*' 159 | content: '(?P(^(?P[ ]+).*$\n))(?P(^([ \t]+.*|[ \t]*)$\n)*)' 160 | close: '(^(?![ \t]+.*$))' 161 | # Ignore doxygen one line directives 162 | - open: '\.\. (autodoxygenindex|doxygenfunction|doxygenstruct|doxygenclass|doxygennamespace|doxygenconcept|doxygenenum|doxygenenumvalue|doxygentypedef|doxygenunion|doxygendefine|doxygenvariable|doxygenfile|doxygengroup|autodoxygenfile|doxygenpage)::' 163 | content: '[ \S]*' 164 | close: '\n' 165 | # Manual disabling via: #spellcheck-disable 166 | - open : '^.. $' 167 | content: '[\s\S]*?' 168 | close: '^.. $' 169 | - pyspelling.filters.url: 170 | - name: Cpp 171 | # The sources below are simply a placeholder as it cannot be empty 172 | sources: 173 | - ['docs/**/*.cpp', 'doc/**/*.hpp'] 174 | expect_match: false 175 | aspell: 176 | lang: en 177 | pipeline: 178 | - pyspelling.filters.cpp: 179 | block_comments: false 180 | line_comments: false 181 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "liveServer.settings.root": "docs/_build/html", 3 | "liveServer.settings.wait": 1000, 4 | "python.terminal.activateEnvInCurrentTerminal": true, 5 | "[python]": { 6 | "editor.defaultFormatter": "ms-python.black-formatter" 7 | }, 8 | "black-formatter.args": [ 9 | "--config", 10 | "pyproject.toml" 11 | ], 12 | "editor.rulers": [ 13 | 80 14 | ], 15 | "python.testing.pytestArgs": [ 16 | "src", 17 | "tests" 18 | ], 19 | "python.testing.unittestEnabled": false, 20 | "python.testing.pytestEnabled": true 21 | } 22 | -------------------------------------------------------------------------------- /.vscode/tasks.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "2.0.0", 3 | "tasks": [ 4 | { 5 | "label": "Build Docs", 6 | "type": "process", 7 | "command": "just", 8 | "args": [ 9 | "docs" 10 | ], 11 | "problemMatcher": [ 12 | { 13 | "owner": "sphinx", 14 | "fileLocation": "absolute", 15 | "pattern": { 16 | "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):(\\d+):\\s+(WARNING|ERROR):\\s+(.*)$", 17 | "file": 1, 18 | "line": 2, 19 | "severity": 3, 20 | "message": 4 21 | } 22 | }, 23 | { 24 | "owner": "sphinx", 25 | "fileLocation": "absolute", 26 | "pattern": { 27 | "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$", 28 | "file": 1, 29 | "severity": 2, 30 | "message": 3 31 | } 32 | } 33 | ], 34 | "group": { 35 | "kind": "build", 36 | "isDefault": true 37 | } 38 | } 39 | ] 40 | } 41 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ROCm Documentation Core Utilities 2 | 3 | ROCm Docs Core is also distributed as a pip package available from PyPi as 4 | [rocm-docs-core](https://pypi.org/project/rocm-docs-core/) 5 | 6 | ## Purpose 7 | 8 | This repository is comprised of utilities, styling, scripts, and additional HTML content that is common to all ROCm projects' documentation. This greatly aids in maintaining the documentation, as any change to the appearance only needs to be modified in one location. 9 | 10 | ## Usage 11 | 12 | ### Setup 13 | 14 | - Install this repository as a Python package using pip 15 | - From PyPi: `pip install rocm-docs-core` 16 | - From GitHub: `pip install git+https://github.com/ROCm/rocm-docs-core.git`. 17 | 18 | - Set `rocm_docs_theme` as the HTML theme 19 | - Add `rocm_docs` as an extension 20 | - Optionally, add `rocm_docs.doxygen` and `sphinxcontrib.doxylink` as extensions 21 | 22 | For an example, see the [test conf.py](./tests/sites/doxygen/extension/conf.py) 23 | 24 | ### Legacy Setup 25 | 26 | - From the `rocm_docs` package import the function `setup_rocm_docs` into `conf.py` for the ReadTheDocs project. 27 | - Call exactly the following, replacing `` with the name of the project. 28 | 29 | For an example, see the [test legacy conf.py](./tests/sites/doxygen/legacy/conf.py) 30 | 31 | ## Documentation 32 | 33 | The `rocm-docs-core` documentation is viewable at [https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/](https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/) 34 | 35 | ### User Guide 36 | 37 | The User Guide describes how users can make use of functionality in `rocm-docs-core` 38 | 39 | It is viewable at [https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/user_guide/user_guide.html](https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/user_guide/user_guide.html) 40 | 41 | ### Developer Guide 42 | 43 | The Developer Guide provides additional information on the processes in toolchains for `rocm-docs-core` 44 | 45 | It is viewable at [https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/developer_guide/developer_guide.html](https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/developer_guide/developer_guide.html) 46 | 47 | ### Build Documentation Locally 48 | 49 | To build the `rocm-docs-core` documentation locally, run the commands below: 50 | 51 | ```bash 52 | pip install -r requirements.txt 53 | cd docs 54 | python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html 55 | ``` 56 | -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | /_build 2 | /_doxygen 3 | -------------------------------------------------------------------------------- /docs/building_documentation.md: -------------------------------------------------------------------------------- 1 | # Building documentation 2 | 3 | ## GitHub 4 | 5 | If you open a pull request and scroll down to the summary panel, 6 | there is a commit status section. Next to the line 7 | `docs/readthedocs.com:advanced-micro-devices-demo`, there is a `Details` link. 8 | If you click this, it takes you to the Read the Docs build for your pull request. 9 | 10 | ![GitHub PR commit status](data/commit-status.png) 11 | 12 | If you don't see this line, click `Show all checks` to get an itemized view. 13 | 14 | ## Command line 15 | 16 | You can build our documentation via the command line using Python. 17 | 18 | See the `build.tools.python` setting in the [Read the Docs configuration file](https://github.com/ROCm/ROCm/blob/develop/.readthedocs.yaml) for the Python version used by Read the Docs to build documentation. 19 | 20 | See the [Python requirements file](https://github.com/ROCm/ROCm/blob/develop/docs/sphinx/requirements.txt) for Python packages needed to build the documentation. 21 | 22 | Use the Python Virtual Environment (`venv`) and run the following commands from the project root: 23 | 24 | ```sh 25 | python3 -mvenv .venv 26 | 27 | .venv/bin/python -m pip install -r docs/sphinx/requirements.txt 28 | .venv/bin/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html 29 | ``` 30 | 31 | Navigate to `_build/html/index.html` and open this file in a web browser. 32 | 33 | ## Visual Studio Code 34 | 35 | With the help of a few extensions, you can create a productive environment to author and test 36 | documentation locally using Visual Studio (VS) Code. Follow these steps to configure VS Code: 37 | 38 | 1. Install the required extensions: 39 | 40 | * Python: `(ms-python.python)` 41 | * Live Server: `(ritwickdey.LiveServer)` 42 | 43 | 2. Add the following entries to `.vscode/settings.json`. 44 | 45 | ```json 46 | { 47 | "liveServer.settings.root": "/.vscode/build/html", 48 | "liveServer.settings.wait": 1000, 49 | "python.terminal.activateEnvInCurrentTerminal": true 50 | } 51 | ``` 52 | 53 | * `liveServer.settings.root`: Sets the root of the output website for live previews. Must be changed 54 | alongside the `tasks.json` command. 55 | * `liveServer.settings.wait`: Tells the live server to wait with the update in order to give Sphinx time to 56 | regenerate the site contents and not refresh before the build is complete. 57 | * `python.terminal.activateEnvInCurrentTerminal`: Activates the automatic virtual environment, so you 58 | can build the site from the integrated terminal. 59 | 60 | 3. Add the following tasks to `.vscode/tasks.json`. 61 | 62 | ```json 63 | { 64 | "version": "2.0.0", 65 | "tasks": [ 66 | { 67 | "label": "Build Docs", 68 | "type": "process", 69 | "windows": { 70 | "command": "${workspaceFolder}/.venv/Scripts/python.exe" 71 | }, 72 | "command": "${workspaceFolder}/.venv/bin/python3", 73 | "args": [ 74 | "-m", 75 | "sphinx", 76 | "-j", 77 | "auto", 78 | "-T", 79 | "-b", 80 | "html", 81 | "-d", 82 | "${workspaceFolder}/.vscode/build/doctrees", 83 | "-D", 84 | "language=en", 85 | "${workspaceFolder}/docs", 86 | "${workspaceFolder}/.vscode/build/html" 87 | ], 88 | "problemMatcher": [ 89 | { 90 | "owner": "sphinx", 91 | "fileLocation": "absolute", 92 | "pattern": { 93 | "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):(\\d+):\\s+(WARNING|ERROR):\\s+(.*)$", 94 | "file": 1, 95 | "line": 2, 96 | "severity": 3, 97 | "message": 4 98 | } 99 | }, 100 | { 101 | "owner": "sphinx", 102 | "fileLocation": "absolute", 103 | "pattern": { 104 | "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$", 105 | "file": 1, 106 | "severity": 2, 107 | "message": 3 108 | } 109 | } 110 | ], 111 | "group": { 112 | "kind": "build", 113 | "isDefault": true 114 | } 115 | } 116 | ] 117 | } 118 | ``` 119 | 120 | > Implementation detail: two problem matchers were needed to be defined, 121 | > because VS Code doesn't tolerate some problem information being potentially 122 | > absent. While a single regex could match all types of errors, if a capture 123 | > group remains empty (the line number doesn't show up in all warning/error 124 | > messages) but the `pattern` references said empty capture group, VS Code 125 | > discards the message completely. 126 | 127 | 4. Configure the Python virtual environment (`venv`). 128 | 129 | From the Command Palette, run `Python: Create Environment`. Select `venv` environment and 130 | `docs/sphinx/requirements.txt`. 131 | 132 | 5. Build the docs. 133 | 134 | Launch the default build task using one of the following options: 135 | 136 | * A hotkey (the default is `Ctrl+Shift+B`) 137 | * Issuing the `Tasks: Run Build Task` from the Command Palette 138 | 139 | 6. Open the live preview. 140 | 141 | Navigate to the site output within VS Code: right-click on `.vscode/build/html/index.html` and 142 | select `Open with Live Server`. The contents should update on every rebuild without having to 143 | refresh the browser. 144 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | """Configuration file for the Sphinx documentation builder. 2 | 3 | This file only contains a selection of the most common options. For a full 4 | list see the documentation: 5 | https://www.sphinx-doc.org/en/master/usage/configuration.html 6 | 7 | For a list of options specific to rocm-docs-core, see the user guide: 8 | https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/ 9 | """ 10 | 11 | # Disable fetching projects.yaml, it would be the same as the local one anyway 12 | # except if a PR modifies it. We want to test with its version in that case 13 | external_projects_remote_repository = "" 14 | external_projects = ["hipify", "python", "rocm-docs-core", "rocm"] 15 | external_projects_current_project = "rocm-docs-core" 16 | 17 | setting_all_article_info = True 18 | all_article_info_os = [] 19 | all_article_info_author = "" 20 | # specific settings override any general settings (eg: all_article_info_) 21 | article_pages = [ 22 | { 23 | "file": "index", 24 | "os": ["linux", "windows"], 25 | "author": "Author: AMD", 26 | "date": "2024-07-03", 27 | "read-time": "2 min read", 28 | }, 29 | { 30 | "file": "user_guide/article_info", 31 | "os": [], 32 | "author": "", 33 | "date": "", 34 | "read-time": "", 35 | }, 36 | { 37 | "file": "developer_guide/commitizen", 38 | }, 39 | ] 40 | 41 | html_theme = "rocm_docs_theme" 42 | html_theme_options = {"flavor": "rocm"} 43 | 44 | external_toc_path = "./sphinx/_toc.yml" 45 | 46 | extensions = ["rocm_docs", "rocm_docs.doxygen"] 47 | doxygen_root = "demo/doxygen" 48 | doxysphinx_enabled = True 49 | doxygen_project = { 50 | "name": "doxygen", 51 | "path": "demo/doxygen/xml", 52 | } 53 | 54 | version = "1.20.0" 55 | release = "1.20.0" 56 | html_title = f"ROCm Docs Core {version}" 57 | project = "ROCm Docs Core" 58 | author = "Advanced Micro Devices, Inc." 59 | copyright = ( 60 | "Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved." 61 | ) 62 | -------------------------------------------------------------------------------- /docs/data/commit-status.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/docs/data/commit-status.png -------------------------------------------------------------------------------- /docs/demo/doxygen/.gitignore: -------------------------------------------------------------------------------- 1 | /html 2 | /xml 3 | -------------------------------------------------------------------------------- /docs/demo/sources/example.hpp: -------------------------------------------------------------------------------- 1 | /// 2 | /// \file 3 | /// \author Jon Doe (jon@example.com) 4 | /// \brief Example doxygen header 5 | /// \version 0.1 6 | /// \date 2023-03-23 7 | /// 8 | /// \copyright Copyright (c) 2023 Advanced Micro Devices Inc. 9 | 10 | #include "example1.hpp" 11 | 12 | /// 13 | /// \brief A namespace 14 | namespace example { 15 | 16 | /// 17 | /// \brief Example class 18 | class Example { 19 | public: 20 | /// 21 | /// \brief This is a method taking no arguments 22 | void method(); 23 | 24 | /// 25 | /// \brief Example method taking parameters 26 | /// \param param The parameter 27 | /// \return description of the return value 28 | int method2(int param); 29 | protected: 30 | /// 31 | /// \brief This is a protected static member 32 | static int static_member; 33 | private: 34 | /// 35 | /// \brief This is a private static method 36 | static void static_method(); 37 | }; 38 | 39 | /// 40 | /// \brief Example class 2 to showcase class hierarchies 41 | class Example2 : public Example {}; 42 | 43 | /// 44 | /// \brief Example of a template function 45 | /// 46 | /// \tparam T Template parameter 47 | /// \param a parameter 48 | template 49 | void template_fun(T a); 50 | 51 | } // namespace example 52 | 53 | /// 54 | /// \brief A function in the global scope 55 | /// 56 | void freestanding_function(); 57 | 58 | /// 59 | /// \defgroup group1 First Group 60 | /// @{ 61 | 62 | /// 63 | /// \brief A struct 64 | /// 65 | struct struct_in_group_1 {}; 66 | 67 | /// 68 | /// @} 69 | 70 | /// 71 | /// \defgroup group2 Second Group 72 | 73 | /// 74 | /// \brief An enumeration 75 | /// \ingroup group2 76 | enum Enum { 77 | Value1 = 1, ///< First Enumerator 78 | Value2 = 17, ///< Second Enum 79 | Undocumented // Undocumented 80 | }; 81 | -------------------------------------------------------------------------------- /docs/demo/sources/example1.hpp: -------------------------------------------------------------------------------- 1 | /** 2 | * \file 3 | * \author Jon Doe (jon@example.com) 4 | * \brief This file is here to showcase include hierarchies 5 | * \version 0.1 6 | * \date 2023-03-23 7 | * 8 | * \copyright Copyright (c) 2023 Advanced Micro Devices Inc. 9 | * 10 | */ 11 | -------------------------------------------------------------------------------- /docs/developer_guide/commitizen.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Commitizen enforces conventional commits and implements automatic release tagging based on commit messages." 5 | "keywords": "Commit, Conventional commit, Commit messages, Commit using Commitizen, Commitizen, Documentation configuration" 6 | --- 7 | 8 | # Commitizen 9 | 10 | The ROCm Docs Core repository uses 11 | [Commitizen](https://commitizen-tools.github.io/commitizen/) to enforce 12 | [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and 13 | implement automatic release tagging based on commit messages. 14 | 15 | ## Commit message rules 16 | 17 | A commit message should like like this: 18 | 19 | ```text 20 | [optional scope]: 21 | 22 | [optional body] 23 | 24 | [optional footer(s)] 25 | ``` 26 | 27 | Commit messages start with a header line that notes the type of change, followed 28 | by an optional list of scopes, then the description of the change. 29 | 30 | Type must be one of: 31 | 32 | - **`build`**: Changes that affect the build system or external dependencies 33 | (example scopes: `gulp`, `broccoli`, `npm`) 34 | - **`ci`**: Changes to our CI configuration files and scripts 35 | - **`docs`**: Documentation only changes 36 | - **`feat`**: A new feature, *corresponds to a minor version bump* 37 | - **`fix`**: A bug fix, *correspond to a patch version bump* 38 | - **`perf`**: A code change that improves performance 39 | - **`refactor`**: A code change that neither fixes a bug nor adds a feature 40 | - **`style`**: Changes that do not affect the meaning of the code (white-space, 41 | formatting, missing semi-colons, etc) 42 | - **`test`**: Adding missing tests or correcting existing tests 43 | - **`chore`**: Other changes that don't modify source code, test or build files 44 | (e.g changing `.gitignore`) 45 | 46 | The **scope** if included should be the area the change affects in parentheses 47 | i.e. `(theme)` for theming changes or `(deps)` for changes to the list of 48 | dependencies. 49 | Multiple scopes can be given and `(all)` may be used if change affects the 50 | entire project. 51 | 52 | The **subject** should be a succinct description of the change in present imperative 53 | tense (i.e. *update wording* not *updated wording*) 54 | 55 | A longer description can be included in the **body**, including the motivation 56 | of the change and comparison with the previous version. Comparisons with the 57 | prior state if shouldn't detail literal changes, those are recorded by the git 58 | history, but the semantic or higher level effect of the modifications. 59 | 60 | The footer contains information about **Breaking Changes** and references to 61 | GitHub issues that the change closes or relates to. 62 | Breaking changes should be noted with the words `BREAKING CHANGE:` followed by 63 | a space and the description of the change. Including a breaking change in a 64 | commit will result in a major version bump of the next release including such 65 | commit. 66 | 67 | For a more detailed description of conventional commits please refer to the 68 | specification linked above. 69 | 70 | ## Committing with Commitizen 71 | 72 | Commitizen contains a utility to walk through making a commit following the 73 | rules above. 74 | 75 | ### Installation 76 | 77 | Commitizen is marked as a "development" dependency of `rocm-docs-core,` 78 | installable via `pip install .[development]` from the root of the repository. 79 | 80 | ### Usage 81 | 82 | Run `cz commit` or `cz c` to start making a commit after staging the files to 83 | be added. Commitizen will ask for each part of the commit message in turn. 84 | 85 | Refer to the documentation of Commitizen (linked above) on other options, and 86 | other features of Commitizen. 87 | -------------------------------------------------------------------------------- /docs/developer_guide/dependabot.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Dependabot is automated dependency management tool" 5 | "keywords": "Automated dependency management tool, Dependency management, Dependabot, Documentation dependencies" 6 | --- 7 | 8 | # Dependabot 9 | 10 | Dependabot is automated dependency management tool. 11 | It is used to keep ROCm documentation dependencies up to date. 12 | 13 | [Here is an example PR that dependabot made on the ROCm repository](https://github.com/ROCm/ROCm/pull/2273) 14 | 15 | [Dependabot Configuration used by this project](https://github.com/ROCm/rocm-docs-core/blob/develop/.github/dependabot.yml) 16 | 17 | [GitHub Dependabot Configuration Guide](https://docs.github.com/en/code-security/dependabot) 18 | -------------------------------------------------------------------------------- /docs/developer_guide/developer_guide.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "A collection of utilities, styling, scripts, and additional HTML content common to all ROCm project documentation" 5 | "keywords": "Documentation processes, Documentation toolchains, Documentation configuration" 6 | --- 7 | 8 | # Developer Guide 9 | 10 | The Developer Guide provides additional information on the processes and toolchains in `rocm-docs-core` 11 | -------------------------------------------------------------------------------- /docs/developer_guide/just.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Just is a command runner used to quickly setup an environment for documentation development" 5 | "keywords": "Documentation development environment, Environment for documentation development, Just, Documentation configuration" 6 | --- 7 | 8 | # Just 9 | 10 | [`just`](https://github.com/casey/just) is a command runner used to 11 | quickly setup an environment for documentation development. 12 | 13 | The aim is to make contributing to `rocm-docs-core` more approachable 14 | by providing ready-to-use environments for development. 15 | 16 | ## Usage 17 | 18 | ### Setting up a development environment 19 | 20 | `just devenv` 21 | 22 | This creates a Python virtual environment, 23 | installs the dependencies, and sets up the pre-commit hooks. 24 | 25 | ### Running linting commands 26 | 27 | > These commands work on both Linux and Windows 28 | 29 | `just check-codestyle` 30 | 31 | Check files for formatting errors and report them. 32 | 33 | `just fix-codestyle` 34 | 35 | Automatically fix errors that have suggested fixes. 36 | 37 | ## GitHub 38 | 39 | GitHub Actions CI is extended to run these tools on PRs 40 | (using the `just`-based entry-points). 41 | 42 | Development container setup and settings are added 43 | for Visual Studio Development containers (and GitHub Codespaces) and Gitpod. 44 | 45 | - [VS Code Dev Containers Guide](https://code.visualstudio.com/docs/devcontainers/containers) 46 | - [Dev Container Dockerfile and Configuration](https://github.com/ROCm/rocm-docs-core/tree/develop/.devcontainer) 47 | - [Gitpod Guide](https://www.gitpod.io/docs/introduction/getting-started) 48 | - [Gitpod Configuration](https://github.com/ROCm/rocm-docs-core/blob/develop/.gitpod.yml) 49 | -------------------------------------------------------------------------------- /docs/developer_guide/projects_yaml.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Defining external intersphinx project mapping" 5 | "keywords": "Intersphinx, project mapping, Documentation configuration" 6 | --- 7 | 8 | # External Intersphinx Project Mapping 9 | 10 | Projects should be defined in `projects.yaml` and should set which key they correspond to by setting external_projects_current_project to this key. 11 | 12 | ## Example 13 | 14 | Given the following `projects.yaml` file: 15 | 16 | ```yaml 17 | projects: 18 | python: https://docs.python.org/3/ 19 | rtd: https://docs.readthedocs.io/en/stable/ 20 | sphinx: https://www.sphinx-doc.org/en/master/ 21 | rocm-docs-core: https://rocm.docs.amd.com/projects/rocm-docs-core/en/${version} 22 | ``` 23 | 24 | The `conf.py` from `rocm-docs-core` should contain: 25 | 26 | ```python3 27 | external_projects_current_project = "rocm-docs-core" 28 | ``` 29 | 30 | Adds support for specifying the "development" branch for each project defined in `projects.yaml`. 31 | This is achieved by setting the `development_branch` key for the project: 32 | 33 | ```yaml 34 | projects: 35 | ... 36 | project: 37 | target: 38 | development_branch: master 39 | ``` 40 | 41 | With this the mapping between projects is changed to the following: 42 | 43 | Development branches map between each other. 44 | Essentially, links on project A's `develop` branch point to the project B's `master` branch. 45 | Vice-versa if A has set its `development_branch` to `develop` and B sets it to `master`. 46 | 47 | Symbolic versions "latest" and "stable" map to themselves in other projects. 48 | 49 | Any other branch maps to "latest". 50 | 51 | ## Explicitly list external projects 52 | 53 | By default the inventories of all external projects defined in `projects.yaml` 54 | will be downloaded. This can take a long time as it requires a network request 55 | for each external project. 56 | 57 | The `external_projects` configuration option can be set to a list with the names 58 | of remote projects to fetch inventories from & enable links to. 59 | The list must be a subset of the project names defined in `projects.yaml`. 60 | The default value of `"all"` means to fetch all projects. 61 | 62 | Intersphinx references to projects that are not in `external_projects` will not 63 | be resolved. References in the the TOC like `${project:project_name}` will 64 | continue to be resolved to the URL of `project_name`, even if `project_name` is 65 | not set in `external_projects` (but it's defined in `projects.yaml`). 66 | -------------------------------------------------------------------------------- /docs/developer_guide/python_linting.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Tools used for checking correctness in Python code" 5 | "keywords": "Python linting tool, Error checker, Documentation configuration" 6 | --- 7 | 8 | # Python Linting 9 | 10 | The following list of tools is used for checking correctness in Python code. 11 | These tools are set up to run as [git pre-commit hooks](https://pre-commit.com/) 12 | via [pre-commit](https://github.com/pre-commit/pre-commit). 13 | 14 | - [`Ruff`](https://github.com/astral-sh/ruff) for linting 15 | - [Usage](https://github.com/astral-sh/ruff#usage) 16 | - [`Mypy`](https://github.com/python/mypy) for static type checking 17 | - [Usage](https://github.com/python/mypy#quick-start) 18 | - [`Black`](https://github.com/psf/black) for code formatting 19 | - [Usage](https://github.com/psf/black#usage) 20 | - [`isort`](https://github.com/PyCQA/isort) for import sorting 21 | - [Usage](https://github.com/PyCQA/isort#using-isort) 22 | 23 | Some non-Python-specific hooks are also enabled: 24 | 25 | - Check `yaml`, `toml`, and `json` validity 26 | - Check for no trailing whitespaces and additional newline at the end of files 27 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "A collection of utilities, styling, scripts, and additional HTML content common to all ROCm project documentation" 5 | "keywords": "ROCm documentation configuration, ROCm documentation customization, ROCm documentation tool, ROCm docs core developer guide" 6 | --- 7 | 8 | # ROCm Docs Core 9 | 10 | ROCm Docs Core is a collection of utilities, styling, scripts and additional 11 | HTML content common to all ROCm projects' documentation. 12 | 13 | ROCm Docs Core is distributed as a pip package available from PyPi as 14 | [rocm-docs-core](https://pypi.org/project/rocm-docs-core/) 15 | 16 | ## Overview 17 | 18 | ::::{grid} 1 1 2 2 19 | :gutter: 1 20 | 21 | :::{grid-item-card} {doc}`User Guide` 22 | :class-body: rocm-card-banner rocm-hue-1 23 | 24 | - {doc}`/user_guide/spellcheck` 25 | - {doc}`/user_guide/linting` 26 | - {doc}`/user_guide/linking` 27 | - {doc}`/user_guide/article_info` 28 | - {doc}`/user_guide/doxygen_integration` 29 | 30 | ::: 31 | 32 | :::{grid-item-card} {doc}`Developer Guide` 33 | :class-body: rocm-card-banner rocm-hue-6 34 | 35 | - {doc}`/developer_guide/just` 36 | - {doc}`/developer_guide/python_linting` 37 | - {doc}`/developer_guide/commitizen` 38 | - {doc}`/developer_guide/projects_yaml` 39 | - {doc}`/developer_guide/dependabot` 40 | 41 | ::: 42 | 43 | :::{grid-item-card} Demo Doxygen Documentation Integration 44 | :class-body: rocm-card-banner rocm-hue-12 45 | 46 | - {doc}`/demo/doxygen/html/index` 47 | 48 | ::: 49 | 50 | :::: 51 | -------------------------------------------------------------------------------- /docs/license.md: -------------------------------------------------------------------------------- 1 | # License 2 | 3 | ```{include} ../LICENSE.txt 4 | ``` 5 | -------------------------------------------------------------------------------- /docs/sphinx/.gitignore: -------------------------------------------------------------------------------- 1 | /_toc.yml 2 | -------------------------------------------------------------------------------- /docs/sphinx/_toc.yml.in: -------------------------------------------------------------------------------- 1 | # Variables of the form ${} are substituted, currently the following 2 | # list is supported: 3 | # - ${branch} (or {branch}) the name of the current branch 4 | # - ${url} (or {url}) github url of the current project 5 | # - ${project:} base url of the documentation of 6 | # based on intersphinx_mapping. 7 | # These comments will also be removed. 8 | defaults: 9 | numbered: False 10 | maxdepth: 6 11 | root: index.md 12 | subtrees: 13 | - entries: 14 | - file: user_guide/user_guide 15 | subtrees: 16 | - entries: 17 | - file: user_guide/spellcheck 18 | - file: user_guide/linting 19 | - file: user_guide/linking 20 | subtrees: 21 | - entries: 22 | - file: user_guide/linking_md 23 | - file: user_guide/linking_rst 24 | - file: user_guide/linking_toc 25 | - file: user_guide/doxygen_integration 26 | - file: user_guide/article_info 27 | - file: developer_guide/developer_guide 28 | subtrees: 29 | - entries: 30 | - file: developer_guide/just 31 | - file: developer_guide/python_linting 32 | - file: developer_guide/commitizen 33 | - file: developer_guide/projects_yaml 34 | - file: developer_guide/dependabot 35 | - caption: Demo Doxygen Documentation Integration 36 | entries: 37 | - file: demo/doxygen/html/index 38 | title: Library API Doxygen Demo 39 | - caption: Demo Table of Contents Tree 40 | entries: 41 | - url: "{url}" 42 | - url: ${project:python} 43 | - url: ${project:rocm-docs-core} 44 | - url: ${project:hipify} 45 | title: HIPIFY 46 | - caption: About 47 | entries: 48 | - file: building_documentation 49 | - file: toolchain 50 | - file: license 51 | -------------------------------------------------------------------------------- /docs/toolchain.md: -------------------------------------------------------------------------------- 1 | # ROCm documentation toolchain 2 | 3 | ROCm documentation relies on several open source toolchains and sites. 4 | Here is a list of a few important ones. 5 | 6 | ## rocm-docs-core 7 | 8 | [rocm-docs-core](https://github.com/ROCm/rocm-docs-core) is an AMD-maintained 9 | project that applies customizations for the ROCm documentation. This project is the tool most ROCm repositories use as part of their documentation build pipeline. It is available as a [pip package on PyPI](https://pypi.org/project/rocm-docs-core/). 10 | 11 | ## Sphinx 12 | 13 | [Sphinx](https://www.sphinx-doc.org/en/master/) is a documentation generator originally used for Python. It is now widely used in the open source community. 14 | 15 | ### Sphinx External ToC 16 | 17 | [Sphinx External ToC](https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) is a Sphinx extension used for ROCm documentation navigation. This tool generates a navigation menu on the left 18 | based on a YAML file (`_toc.yml.in`) that contains the table of contents. 19 | 20 | ### Sphinx-book-theme 21 | 22 | [Sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/en/latest/) is a Sphinx theme that defines the base appearance for ROCm documentation. ROCm documentation applies some customization, such as a custom header and footer, on top of the Sphinx Book Theme. 23 | 24 | ### Sphinx Design 25 | 26 | [Sphinx design](https://sphinx-design.readthedocs.io/en/latest/index.html) is a Sphinx extension that adds design functionality. ROCm documentation uses Sphinx Design for grids, cards, and synchronized tabs. 27 | 28 | ## Doxygen 29 | 30 | [Doxygen](https://www.doxygen.nl/) is a documentation generator that extracts information from in-code comments. It is used for API documentation. 31 | 32 | ## Breathe 33 | 34 | [Breathe](https://www.breathe-doc.org/) is a Sphinx plugin for integrating Doxygen content. 35 | 36 | ## MyST 37 | 38 | [Markedly Structured Text (MyST)](https://myst-tools.org/docs/spec) is an extended flavor of Markdown ([CommonMark](https://commonmark.org/)) influenced by reStructuredText (RST) and Sphinx. It is integrated into the ROCm documentation with the [`myst-parser`](https://myst-parser.readthedocs.io/en/latest/) Sphinx extension. 39 | 40 | See the [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) at the Jupyter Book site. 41 | 42 | ## Read the Docs 43 | 44 | [Read the Docs](https://docs.readthedocs.io/en/stable/) is the service that builds and hosts the HTML version of the ROCm documentation. 45 | -------------------------------------------------------------------------------- /docs/user_guide/article_info.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Setting article info in ROCm documentation" 5 | "keywords": "Documentation settings, Display document information, Display article metadata, Display document metadata" 6 | --- 7 | 8 | # Article Info 9 | 10 | Article info is disabled by default and must be enabled in `conf.py`. 11 | 12 | ## Settings 13 | 14 | *Legend: `setting name (setting data type):` explanation* 15 | 16 | - `setting_all_article_info (bool)`: Setting this value to true will enable article info for all pages and use default values. See possible settings for default values. 17 | 18 | - `all_article_info_os (list[str])`: Determines which supported OS appear in the article info. Possible strings are `"linux"` and `"windows"`. Default value is `["linux"]`. 19 | 20 | - `all_article_info_author (str)`: Determines the author. Default is empty string. 21 | 22 | - `all_article_info_date (str)`: Determines date of publication. Default is the date the file was last modified in git. 23 | 24 | - `all_article_info_read_time (str)`: Determines the read time. Default is calculated based on the number of words in the file. 25 | 26 | - `article_pages (list[dict])`: Used for specific settings for a page. These override any of the general settings above (eg: `all_article_info_`). 27 | 28 | Example: 29 | 30 | ```python 31 | article_pages = [ 32 | { 33 | "file":"index", 34 | "os":["linux", "windows"], 35 | "author":"Author: AMD", 36 | "date":"2023-05-01", 37 | "read-time":"2 min read" 38 | }, 39 | {"file":"developer_guide/commitizen"} 40 | ] 41 | ``` 42 | -------------------------------------------------------------------------------- /docs/user_guide/doxygen_integration.md: -------------------------------------------------------------------------------- 1 | # Doxygen Integration 2 | 3 | ## What 4 | 5 | `doxysphinx` is a package that handles integration 6 | of Doxygen and Sphinx documentation. 7 | 8 | `doxysphinx` allows displaying Doxygen documentation in the Sphinx documentation. 9 | 10 | `rocm-docs-core` applies some additional formatting and styling on top of this 11 | to stay in line with our themes. 12 | 13 | Since `doxysphinx` automatically integrates the Doxygen documentation, 14 | developers only have to update the documentation strings in the source code 15 | if they are formatted for Doxygen. 16 | 17 | For more information on `doxysphinx`, see the [GitHub repository](https://github.com/boschglobal/doxysphinx) 18 | or the [doxysphinx documentation](https://boschglobal.github.io/doxysphinx/). 19 | 20 | ## How 21 | 22 | Some examples of how to use `doxysphinx` with `rocm-docs-core` are included below. 23 | 24 | Assuming Doxygen documentation is already configured correctly, 25 | several changes must be made to the configuration file (`conf.py`) 26 | located in the `docs` folder 27 | and the requirements files (`requirements.in` and `requirements.txt`) 28 | located in the `sphinx` folder. 29 | 30 | For the configuration file: 31 | 32 | - Include the `rocm_docs.doxygen` extension in the `extensions` list. 33 | 34 | - Include the path to the Doxygen configuration in `doxygen_root`. For ROCm projects, this value is usually `doxygen`. 35 | 36 | - Set `doxysphinx_enabled` to True. 37 | 38 | - Define a `doxygen_project` dictionary and set a `name` and `path`. For ROCm projects, the value of path is usually `doxygen/xml`. 39 | 40 | For the requirements files: 41 | 42 | - Specify the `api_reference` in the `requirements.in` (example: `rocm-docs-core[api_reference]==0.36.0`) 43 | 44 | - Use `pip-tools` to compile the `requirements.in` 45 | 46 | - `pip install pip-tools` 47 | 48 | - `pip-compile requirements.in --resolver=backtracking` 49 | 50 | Then add the Doxygen output to the table of contents (`_toc.yml.in`). 51 | 52 | Optionally, specify custom style sheets to use in the Doxygen configuration (`Doxyfile`). 53 | These style sheets are a part of `rocm-docs-core`. 54 | 55 | - `HTML_HEADER` 56 | 57 | - `HTML_FOOTER` 58 | 59 | - `HTML_STYLESHEET` 60 | 61 | - `HTML_EXTRA_STYLESHEET` 62 | 63 | When building the documentation with the API reference enabled, 64 | the console output will also make configuration recommendations to make 65 | documentation builds succeed. 66 | If documentation builds are still failing, please follow the recommendations. 67 | 68 | This project has [Demo Doxygen Docs here](../demo/doxygen/html/index). 69 | See the [source code](https://github.com/ROCm/rocm-docs-core) for details. 70 | 71 | The `tests` folder in the `rocm-docs-core` project on GitHub 72 | also has example configuration files. 73 | 74 | See [this PR for a simple example of adding a Doxygen code snippet](https://github.com/ROCm/rocm-docs-core/pull/222). 75 | -------------------------------------------------------------------------------- /docs/user_guide/linking.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Setting up links to other projects, current project and external sites in ROCm documentation" 5 | "keywords": "Adding links, Project linking, Project reference, Documentation settings" 6 | --- 7 | 8 | # Linking 9 | 10 | [Markdown](./linking_md) 11 | 12 | [reStructuredText (RST)](./linking_rst) 13 | -------------------------------------------------------------------------------- /docs/user_guide/linking_md.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Setting up links in Markdown to other projects, current project and external sites in ROCm documentation" 5 | "keywords": "Markdown links, Project linking, Project reference, Adding links in Markdown, Documentation settings" 6 | --- 7 | 8 | # Linking in Markdown 9 | 10 | ## Markdown 11 | 12 | ### Cross References to Other Projects 13 | 14 | The [`projects.yaml`](https://github.com/ROCm/rocm-docs-core/blob/develop/src/rocm_docs/data/projects.yaml) 15 | configuration file contains the names of projects 16 | that should be used when making links that cross-reference documentation sites. 17 | 18 | When making links that cross-reference documentation sites, the following 19 | format should be used: 20 | 21 | ```Markdown 22 | {doc}`Text here` 23 | ``` 24 | 25 | Cross-references are achieved via Intersphinx. 26 | For more information, refer to the 27 | [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) 28 | or [Read the Docs documentation](https://docs.readthedocs.io/en/stable/guides/intersphinx.html) 29 | on Intersphinx. 30 | 31 | #### Example 32 | 33 | The following Markdown: 34 | 35 | ```Markdown 36 | {doc}`ROCm Documentation` 37 | ``` 38 | 39 | will be rendered as the following link: 40 | 41 | {doc}`ROCm Documentation` 42 | 43 | ### Relative Links to Current Project 44 | 45 | #### Example 46 | 47 | The following Markdown: 48 | 49 | ```Markdown 50 | [Link Text](../index) 51 | ``` 52 | 53 | will be rendered as the following link: 54 | 55 | [Link Text](../index) 56 | 57 | ### Absolute Links to External Sites 58 | 59 | For other links, usual Markdown conventions should be used. 60 | 61 | #### Example 62 | 63 | The following Markdown: 64 | 65 | ```Markdown 66 | [Link Text](https://github.com/ROCm/ROCm) 67 | ``` 68 | 69 | will be rendered as the following link: 70 | 71 | [Link Text](https://github.com/ROCm/ROCm) 72 | -------------------------------------------------------------------------------- /docs/user_guide/linking_rst.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: Setting up links in RST to other projects, current project and external sites in ROCm documentation 3 | :keywords: RST links, Project linking, Project reference, Adding links in RST, Documentation settings 4 | 5 | 6 | Linking in RST 7 | ============== 8 | 9 | reStructuredText (RST) 10 | ---------------------- 11 | 12 | Cross References to Arbitrary Locations in Other Projects 13 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 14 | 15 | The `projects.yaml `_ 16 | configuration file contains the names of projects 17 | that should be used when making links that cross-reference documentation sites. 18 | 19 | Cross references to anchors or arbitrary locations in documentation 20 | can be done using labels. 21 | 22 | See the `Sphinx documentation on cross-referencing arbitrary locations `_ 23 | for information on labels. 24 | 25 | The format using a label would appear as follows: 26 | 27 | .. code-block:: RST 28 | 29 | :ref:`Text here` 30 | 31 | Cross-references are achieved via Intersphinx. 32 | For more information, refer to the 33 | `Sphinx documentation `_ 34 | or `Read the Docs documentation `_ 35 | on Intersphinx. 36 | 37 | Example 38 | ^^^^^^^ 39 | 40 | The following RST: 41 | 42 | .. code-block:: RST 43 | 44 | :ref:`ROCm for AI Install` 45 | 46 | will be rendered as the following link: 47 | 48 | :ref:`ROCm for AI Install` 49 | -------------------------------------------------------------------------------- /docs/user_guide/linking_toc.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Setting up links in the Table of Contents for ROCm documentation" 5 | "keywords": "Links in TOC, Links in table of content, Documentation TOC, Documentation table of content, Document index, Documentation settings" 6 | --- 7 | 8 | # Linking in the Table of Contents 9 | 10 | ## Syntax 11 | 12 | Variables of the form `${}` are substituted, currently the following 13 | list is supported: 14 | 15 | - `${branch}` or `{branch}`: the name of the current branch 16 | - `${url}` or `{url}`: GitHub URL of the current project 17 | - `${project:}`: base URL of the documentation of `` 18 | based on Intersphinx mapping 19 | 20 | ### Example 21 | 22 | ```in 23 | - url: "{url}/tree/{branch}" 24 | - url: ${project:python} 25 | - url: ${project:rocm-docs-core} 26 | - url: ${project:hipify} 27 | ``` 28 | -------------------------------------------------------------------------------- /docs/user_guide/linting.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Linting ensures correct Markdown and ReStructuredText formatting on every pull request" 5 | "keywords": "Formatting PR, Formatting pull requests, Linting checks, Documentation settings" 6 | --- 7 | 8 | # Linting 9 | 10 | `rocm-docs-core` has linting to ensure correct Markdown and ReStructuredText 11 | formatting on every pull request (PR) via GitHub Actions. 12 | 13 | If a PR fails linting, the errors must be addressed before it can be merged. 14 | 15 | The results of linting is viewable in the "Checks" tab for a PR. 16 | 17 | ## Markdown Linting 18 | 19 | The current linter used for Markdown is [`markdownlint`](https://github.com/DavidAnson/markdownlint), 20 | which uses the [following rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). 21 | 22 | ### Optional 23 | 24 | `markdownlint` can also be installed and run locally using the [`markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on [Visual Studio Code](https://code.visualstudio.com/Download). 25 | -------------------------------------------------------------------------------- /docs/user_guide/spellcheck.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "Rocm docs core has spell checks run on every pull request" 5 | "keywords": "Spell check in ROCm documentation, Spell check in ROCm docs core, ROCm docs core user guide" 6 | --- 7 | 8 | # Spell Check 9 | 10 | `rocm-docs-core` has spell checks run on every pull request (PR) via GitHub Actions. 11 | 12 | If a PR fails spell check, the errors must be addressed before it can be merged. 13 | 14 | The results of a spell check is viewable in the "Checks" tab for a PR. 15 | 16 | ## Types of Errors 17 | 18 | ### Spelling Mistake 19 | 20 | View the "Details" for a spell check and fix the misspelled words. 21 | 22 | ### New words or Acronyms 23 | 24 | Spell check may flag errors if it does not recognize a word. 25 | 26 | The reason could be that the word is not familiar to the dictionary used 27 | or an unfamiliar acronym. 28 | 29 | To get spell check to recognize this word, add it to the `.wordlist.txt` file, 30 | located at the root of the project (for this project, `rocm-docs-core`, 31 | that would be the `rocm-docs-core` folder). 32 | 33 | ### Special keywords 34 | 35 | If the word is not meant to be a dictionary word, but is still valid 36 | technical terminology, wrap the word with the backtick (`) key. 37 | 38 | #### Keyword examples 39 | 40 | - File or folder names 41 | - Commands or arguments 42 | - Code blocks 43 | - Names of executables or binaries 44 | 45 | ## More Information 46 | 47 | For more information, see the GitHub Action 48 | [spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions) 49 | -------------------------------------------------------------------------------- /docs/user_guide/user_guide.md: -------------------------------------------------------------------------------- 1 | --- 2 | myst: 3 | html_meta: 4 | "description": "The user guide describes how users can make use of functionalities in ROCm docs core" 5 | "keywords": "ROCm docs core functionalities, Documentation settings" 6 | --- 7 | 8 | # User Guide 9 | 10 | The User Guide describes how users can make use of functionality in `rocm-docs-core` 11 | -------------------------------------------------------------------------------- /justfile: -------------------------------------------------------------------------------- 1 | venvdir := ".venv" 2 | base-python := "python" 3 | binfolder := if os_family() == "windows" {"Scripts"} else {"bin"} 4 | bindir := venvdir / binfolder 5 | python := bindir / "python" 6 | ruff_exe := bindir / "ruff" 7 | 8 | verbose_errors := "false" 9 | 10 | set windows-shell := ["powershell.exe", "-c"] 11 | 12 | [unix] 13 | _virtualenv: 14 | [ -d {{venvdir}} ] || {{base-python}} -m venv {{venvdir}} 15 | 16 | [windows] 17 | _virtualenv: 18 | if (-Not (Test-Path {{venvdir}} -PathType Container)) { {{base-python}} -m venv {{venvdir}} } 19 | 20 | _install-defusedxml: _virtualenv 21 | {{python}} -m pip install defusedxml 22 | 23 | _install-pip-tools: _virtualenv 24 | {{python}} -m pip install pip-tools 25 | 26 | # Install development and runtime dependencies 27 | deps: _install-pip-tools 28 | {{python}} -m piptools sync requirements.txt 29 | {{python}} -m mypy --non-interactive --install-types src 30 | 31 | # (Re-)lock the dependencies with pip-compile 32 | lock-deps +extra_args="": 33 | {{python}} -m piptools compile --all-extras {{extra_args}} pyproject.toml 34 | 35 | # Install git-hooks for development 36 | install-git-hooks: 37 | {{python}} -m pre_commit install 38 | 39 | # Set up a development environment 40 | devenv: deps install-git-hooks && install 41 | 42 | # Install the package in editable mode 43 | install: 44 | {{python}} -m pip install -e ".[api_reference]" \ 45 | --config-settings editable_mode=strict 46 | 47 | build: 48 | {{python}} -m build 49 | 50 | _format extra_args +files: 51 | {{python}} -m black --config pyproject.toml {{extra_args}} {{files}} 52 | 53 | format +files="src tests docs": (_format "" files) 54 | check-format +files="src tests docs": (_format "--check" files) 55 | 56 | _isort extra_args +files: 57 | {{python}} -m isort --settings-path pyproject.toml {{extra_args}} {{files}} 58 | 59 | # Sort imports 60 | isort +files="src tests docs": (_isort "" files) 61 | # Check if imports are correctly sorted 62 | check-isort +files="src tests docs": (_isort "--check" files) 63 | 64 | _ruff extra_args +files: 65 | {{ruff_exe}} check --config pyproject.toml {{extra_args}} {{files}} 66 | 67 | # Run ruff to lint files 68 | ruff +files="src tests": (_ruff "" files) 69 | # Run ruff and autolint 70 | fix-ruff +files="src tests": (_ruff "--fix --exit-non-zero-on-fix" files) 71 | 72 | _run-hook hook: 73 | @{{python}} -m pre_commit run --all-files {{ if verbose_errors == "true" {"--show-diff-on-failure"} else {""} }} {{hook}} 74 | 75 | # Run basic pre-commit hooks 76 | hooks: (_run-hook "check-yaml") (_run-hook "check-json") (_run-hook "check-toml") (_run-hook "end-of-file-fixer") (_run-hook "file-contents-sorter") (_run-hook "trailing-whitespace") 77 | 78 | # Run linters, no files are modified 79 | lint +files="src tests": (ruff "" files) hooks 80 | # Run linters, trying to fix errors automatically 81 | fix-lint +files="src tests": (fix-ruff files) hooks 82 | 83 | # Run type-checking 84 | mypy +files="src tests": 85 | {{python}} -m mypy --config-file pyproject.toml {{files}} 86 | 87 | # Run formatting, linters, imports sorting, fixing errors if possible 88 | fix-codestyle +files="src tests": (fix-lint files) (isort files) (format files) 89 | alias codestyle := fix-codestyle 90 | 91 | # Check formatting, linters, imports sorting 92 | check-codestyle +files="src tests": (lint files) (check-isort files) (check-format files) (mypy files) 93 | alias check := check-codestyle 94 | 95 | docs: 96 | {{python}} -m sphinx -j auto -T -b html -d docs/_build/doctrees \ 97 | --color -D language=en docs docs/_build/html 98 | 99 | test +files="src tests": _install-defusedxml 100 | {{python}} -m pytest {{files}} 101 | 102 | _check-commit-mesg file: 103 | {{python}} -m commitizen check --allow-abort --commit-msg-file {{file}} 104 | 105 | _check-commit-range range: 106 | {{python}} -m commitizen check --rev-range {{range}} 107 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = [ 3 | "setuptools>=42", 4 | "wheel" 5 | ] 6 | build-backend = "setuptools.build_meta" 7 | 8 | [project] 9 | name = 'rocm-docs-core' 10 | version = "1.20.0" 11 | authors=[ 12 | {name="Lauren Wrubleski", email="Lauren.Wrubleski@amd.com"} 13 | ] 14 | description ='Core utilities for all ROCm documentation on RTD' 15 | readme="README.md" 16 | classifiers = [ 17 | "Programming Language :: Python :: 3", 18 | "License :: OSI Approved :: MIT License", 19 | "Operating System :: OS Independent" 20 | ] 21 | dependencies = [ 22 | "GitPython>=3.1.30", 23 | "PyGithub>=1.58.1", 24 | "sphinx>=5.3.0", 25 | "breathe>=4.34.0", 26 | "myst-nb>=1.1.2", 27 | "pydata-sphinx-theme==0.15.4", 28 | "sphinx-book-theme>=1.0.1", 29 | "sphinx-copybutton>=0.5.1", 30 | "sphinx-design>=0.3.0", 31 | "sphinx_external_toc>=0.3.1", 32 | "sphinx-notfound-page>=0.8.3", 33 | "pyyaml>=6.0", 34 | "fastjsonschema>=2.16" 35 | ] 36 | requires-python = ">=3.10" 37 | 38 | [project.urls] 39 | repository="https://github.com/ROCm/rocm-docs-core" 40 | documentation="https://rocm.docs.amd.com" 41 | 42 | [project.optional-dependencies] 43 | api_reference = [ 44 | "doxysphinx>=3.3.2" 45 | ] 46 | development = [ 47 | "black>=22.1", 48 | "build>=0.10.0", 49 | "commitizen>=2.42", 50 | "isort>=5.12.0", 51 | "mypy>=1.3.0", 52 | "pip-tools>=6.13.0", 53 | "pre-commit>=3.3.2", 54 | "pytest>=7.4.2", 55 | "ruff>=0.0.269", 56 | "sphinxcontrib.doxylink>=1.12.2" 57 | ] 58 | 59 | [project.entry-points."sphinx.html_themes"] 60 | rocm_docs_theme = "rocm_docs.theme" 61 | 62 | [tool.setuptools.packages.find] 63 | where=["src"] 64 | 65 | [tool.setuptools.package-data] 66 | rocm_docs = ["data/**/*", "rocm_docs_theme/**/*", "py.typed"] 67 | 68 | [tool.black] 69 | target-version = ["py310"] 70 | line-length = 80 71 | color = true 72 | 73 | [tool.commitizen] 74 | name = "cz_conventional_commits" 75 | version = "1.20.0" 76 | version_files = ["pyproject.toml:^version", "docs/conf.py:^(version|release)"] 77 | tag_format = "v$version" 78 | annotated_tag = true 79 | 80 | [tool.isort] 81 | # https://github.com/timothycrosley/isort/ 82 | py_version = "310" 83 | line_length = 80 84 | 85 | known_typing = ["typing", "types", "typing_extensions", "mypy", "mypy_extensions"] 86 | sections = ["FUTURE", "TYPING", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"] 87 | include_trailing_comma = true 88 | profile = "black" 89 | multi_line_output = 3 90 | indent = 4 91 | color_output = true 92 | 93 | [tool.mypy] 94 | allow_redefinition = false 95 | check_untyped_defs = true 96 | color_output = true 97 | disallow_any_generics = true 98 | disallow_incomplete_defs = true 99 | exclude = ["^docs", "^tests/(sites|templates)"] 100 | implicit_reexport = false 101 | pretty = true 102 | python_version = "3.10" 103 | show_column_numbers = true 104 | show_error_codes = true 105 | show_error_context = true 106 | show_traceback = true 107 | strict_equality = true 108 | strict_optional = true 109 | warn_no_return = true 110 | warn_redundant_casts = true 111 | warn_return_any = true 112 | warn_unreachable = true 113 | warn_unused_configs = true 114 | warn_unused_ignores = true 115 | 116 | [tool.ruff] 117 | lint.select = ["ARG","C4","D","E","F","FA","N","PT","RET","RUF","SIM","UP","W"] 118 | lint.ignore = ["E501", "D203", "D213", "D4"] 119 | target-version = "py310" 120 | exclude = ["tests/sites", "tests/templates"] 121 | line-length = 80 122 | 123 | [tool.ruff.lint.per-file-ignores] 124 | "src/**/*" = ["PT"] 125 | "tests/conftest.py" = ["F401", "F403"] 126 | "tests/test_*.py" = ["D"] 127 | 128 | [tool.pytest.ini_options] 129 | markers = [ 130 | "for_all_folders: perform multiple calls based on test folders", 131 | "template_folder: use the folder as a template to copy data over it", 132 | "meta_invert_fixture: invert the meaning of the fixture for testing" 133 | ] 134 | addopts = ["--doctest-modules", "--ignore=tests/sites"] 135 | filterwarnings = """ 136 | ignore::DeprecationWarning 137 | default::DeprecationWarning:rocm_docs 138 | default::PendingDeprecationWarning:rocm_docs 139 | ignore::PendingDeprecationWarning 140 | default::DeprecationWarning:tests 141 | default::DeprecationWarning:rocm_docs 142 | """ 143 | -------------------------------------------------------------------------------- /src/rocm_docs/__init__.py: -------------------------------------------------------------------------------- 1 | """Defines the ROCmDocs package. 2 | 3 | Set up variables for documentation of ROCm projects 4 | that are using Read the Docs. 5 | """ 6 | 7 | from __future__ import annotations 8 | 9 | from typing import ClassVar, TypeAlias 10 | 11 | import os 12 | 13 | from rocm_docs.core import setup 14 | 15 | MaybePath: TypeAlias = str | os.PathLike[str] | None 16 | 17 | 18 | # Intentionally disabling the too-many-instance-attributes check in pylint 19 | # as this class is intended to contain all necessary Sphinx config variables 20 | # pylint: disable=too-many-instance-attributes 21 | class ROCmDocs: 22 | """A class to contain all of the Sphinx variables.""" 23 | 24 | SPHINX_VARS: ClassVar = [ 25 | "extensions", 26 | "html_title", 27 | "html_theme", 28 | "html_theme_options", 29 | "doxygen_root", 30 | "doxygen_project", 31 | "doxyfile", 32 | "doxysphinx_enabled", 33 | ] 34 | 35 | def __init__( 36 | self, 37 | project_name: str, 38 | _: str | None = None, 39 | __: MaybePath = None, 40 | ) -> None: 41 | """Intialize ROCmDocs.""" 42 | self._project_name: str = project_name 43 | self.extensions: list[str] = [] 44 | self.html_title: str 45 | self.html_theme: str 46 | self.html_theme_options: dict[str, str | (bool | list[str])] = {} 47 | self.doxygen_root: MaybePath = None 48 | self.doxygen_project: dict[str, str | None | MaybePath] = { 49 | "name": None, 50 | "path": None, 51 | } 52 | self.doxyfile: MaybePath = None 53 | self.doxysphinx_enabled: bool = False 54 | 55 | @property 56 | def project(self) -> str: 57 | """Sphinx project variable.""" 58 | return self._project_name 59 | 60 | def run_doxygen( 61 | self, 62 | doxygen_root: MaybePath = None, 63 | doxygen_path: MaybePath = None, 64 | doxygen_file: str | None = None, 65 | ) -> None: 66 | """Run doxygen as part of Sphinx by adding rocm_docs.doxygen.""" 67 | if "rocm_docs.doxygen" not in self.extensions: 68 | self.extensions.append("rocm_docs.doxygen") 69 | 70 | self.doxygen_root = doxygen_root 71 | self.doxygen_project = { 72 | "name": self._project_name, 73 | "path": doxygen_path, 74 | } 75 | self.doxyfile = doxygen_file 76 | 77 | def enable_api_reference(self) -> None: 78 | """Enable embedding the doxygen generated api.""" 79 | if "rocm_docs.doxygen" not in self.extensions: 80 | self.extensions.append("rocm_docs.doxygen") 81 | 82 | self.doxysphinx_enabled = True 83 | 84 | def setup(self) -> None: 85 | """Set up default RTD variables.""" 86 | self.extensions.append("rocm_docs") 87 | full_project_name = self._project_name 88 | self.html_title = full_project_name 89 | self.html_theme = "rocm_docs_theme" 90 | 91 | 92 | __all__ = ["ROCmDocs", "setup"] 93 | -------------------------------------------------------------------------------- /src/rocm_docs/article_info.py: -------------------------------------------------------------------------------- 1 | """Logic to add article info to a page. 2 | 3 | For all options see the user guide: 4 | https://rocm.docs.amd.com/projects/rocm-docs-core/en/latest/user_guide/article_info.html 5 | """ 6 | 7 | from typing import Any, cast 8 | 9 | import importlib.resources 10 | import os 11 | import re 12 | from pathlib import Path 13 | 14 | import bs4 15 | import git.repo 16 | from sphinx.application import Sphinx 17 | from sphinx.config import Config 18 | 19 | 20 | def set_article_info(app: Sphinx, _: Config) -> None: 21 | """Add article info headers to HTML pages.""" 22 | if ( 23 | app.config.setting_all_article_info is False 24 | and len(app.config.article_pages) == 0 25 | ): 26 | return 27 | 28 | article_info = ( 29 | importlib.resources.files("rocm_docs") 30 | .joinpath("rocm_docs_theme/components/article-info.html") 31 | .read_text(encoding="utf-8") 32 | ) 33 | 34 | specific_pages: list[str] = [] 35 | 36 | _set_page_article_info(app, article_info, specific_pages) 37 | 38 | if app.config.setting_all_article_info is True: 39 | _set_all_article_info(app, article_info, specific_pages) 40 | 41 | 42 | def _set_page_article_info( 43 | app: Sphinx, article_info: str, specific_pages: list[str] 44 | ) -> None: 45 | """Add article info headers to the configured HTML pages. 46 | 47 | The pages can be set in "article_pages" of the Sphinx configuration. 48 | """ 49 | repo = git.repo.Repo(app.srcdir, search_parent_directories=True) 50 | for page in app.config.article_pages: 51 | path_rel = app.project.doc2path(page["file"], False) 52 | path_html = Path(app.outdir, path_rel).with_suffix(".html") 53 | path_source = Path(app.srcdir, path_rel) 54 | 55 | # FIXME: This will silently skip all files when not building the default 56 | # `html` format (e.g `htmlzip`, `epub` or `pdf`) 57 | if not path_html.is_file(): 58 | continue 59 | 60 | os_list = [] 61 | page.setdefault("os", app.config.all_article_info_os) 62 | if "linux" in page["os"]: 63 | os_list.append("Linux") 64 | if "windows" in page["os"]: 65 | os_list.append("Windows") 66 | article_os_info = " and ".join(os_list) 67 | if os_list: 68 | article_os_info = f"Applies to {article_os_info}" 69 | modified_info = article_info.replace("", article_os_info) 70 | 71 | author = app.config.all_article_info_author 72 | if "author" in page: 73 | author = page["author"] 74 | modified_info = modified_info.replace("", author) 75 | 76 | date_info: str | None = None 77 | if "date" in page: 78 | date_info = page["date"] 79 | else: 80 | date_info = _get_time_last_modified(repo, path_source) 81 | 82 | if date_info == "": 83 | soup = bs4.BeautifulSoup(modified_info, "html.parser") 84 | svg_to_remove = soup.find("span", class_="article-info-date-svg") 85 | if svg_to_remove and isinstance(svg_to_remove, bs4.Tag): 86 | svg_to_remove.decompose() 87 | modified_info = str(soup) 88 | 89 | if date_info is not None: 90 | modified_info = modified_info.replace("", date_info) 91 | 92 | if "read-time" in page: 93 | read_time = page["read-time"] 94 | else: 95 | read_time = _estimate_read_time(path_html) 96 | 97 | if read_time == "": 98 | soup = bs4.BeautifulSoup(modified_info, "html.parser") 99 | svg_to_remove = soup.find( 100 | "span", class_="article-info-read-time-svg" 101 | ) 102 | if svg_to_remove and isinstance(svg_to_remove, bs4.Tag): 103 | svg_to_remove.decompose() 104 | modified_info = str(soup) 105 | 106 | if read_time is not None: 107 | modified_info = modified_info.replace("", read_time) 108 | 109 | specific_pages.append(page["file"]) 110 | _write_article_info(path_html, modified_info) 111 | 112 | 113 | def _set_all_article_info( 114 | app: Sphinx, article_info: str, specific_pages: list[str] 115 | ) -> None: 116 | """Add article info headers with general settings to all HTML pages. 117 | 118 | Pages that have specific settings (configured by "article_pages") are 119 | skipped. 120 | """ 121 | repo = git.repo.Repo(app.srcdir, search_parent_directories=True) 122 | for docname in app.project.docnames: 123 | # skip pages with specific settings 124 | if docname in specific_pages: 125 | continue 126 | 127 | page_rel = app.project.doc2path(docname, False) 128 | page = Path(app.outdir, page_rel).with_suffix(".html") 129 | 130 | # FIXME: This will silently skip all files when not building the default 131 | # `html` format (e.g `htmlzip`, `epub` or `pdf`) 132 | if not page.is_file(): 133 | continue 134 | 135 | os_list = [] 136 | if "linux" in app.config.all_article_info_os: 137 | os_list.append("Linux") 138 | if "windows" in app.config.all_article_info_os: 139 | os_list.append("Windows") 140 | article_os_info = " and ".join(os_list) 141 | if os_list: 142 | article_os_info = f"Applies to {article_os_info}" 143 | 144 | date_info = _get_time_last_modified(repo, Path(app.srcdir, page_rel)) 145 | if not date_info: 146 | date_info = cast(str, app.config.all_article_info_date) 147 | 148 | modified_info = article_info.replace("", article_os_info) 149 | modified_info = modified_info.replace( 150 | "", app.config.all_article_info_author 151 | ) 152 | modified_info = modified_info.replace("", date_info) 153 | modified_info = modified_info.replace( 154 | "", _estimate_read_time(page) 155 | ) 156 | 157 | _write_article_info(page, modified_info) 158 | 159 | 160 | def _get_time_last_modified(repo: git.repo.Repo, path: Path) -> str | None: 161 | try: 162 | time = next( 163 | repo.iter_commits(paths=path, max_count=1) 164 | ).committed_datetime 165 | return time.strftime("%Y-%m-%d") 166 | except StopIteration: 167 | return None 168 | 169 | 170 | def _estimate_read_time(file_name: Path) -> str: 171 | def is_visible(element): 172 | if element.parent.name in [ 173 | "style", 174 | "script", 175 | "[document]", 176 | "head", 177 | "title", 178 | ]: 179 | return False 180 | if isinstance(element, bs4.element.Comment): 181 | return False 182 | return element.string != "\n" 183 | 184 | def count_words(text): 185 | words = re.findall(r"\w+", text) 186 | return len(words) 187 | 188 | words_per_minute = 200 189 | 190 | with open(file_name, encoding="utf-8") as file: 191 | html = file.read() 192 | soup = bs4.BeautifulSoup(html, "html.parser") 193 | page_text = soup.find_all(text=True) 194 | visible_page_text = filter(is_visible, page_text) 195 | average_word_count = sum(count_words(line) for line in visible_page_text) 196 | time_minutes = int(max(1, round(average_word_count / words_per_minute))) 197 | return f"{time_minutes} min read time" 198 | 199 | 200 | def _write_article_info(path: os.PathLike[Any], article_info: str) -> None: 201 | with open(path, "r+", encoding="utf8") as file: 202 | page_html = file.read() 203 | soup = bs4.BeautifulSoup(page_html, "html.parser") 204 | 205 | has_article_info = soup.find("div", id="rocm-docs-core-article-info") 206 | if ( 207 | has_article_info is not None 208 | or soup.article is None 209 | or soup.article.h1 is None 210 | ): 211 | return 212 | 213 | soup.article.h1.insert_after( 214 | bs4.BeautifulSoup(article_info, "html.parser") 215 | ) 216 | file.seek(0) 217 | file.truncate(0) 218 | file.write(str(soup)) 219 | -------------------------------------------------------------------------------- /src/rocm_docs/core.py: -------------------------------------------------------------------------------- 1 | """Core rocm_docs extension. 2 | 3 | It enables a core set of sphinx extensions and provides good defaults for 4 | settings. The environment provided is meant as consistent common base for 5 | ROCm documentation projects. 6 | """ 7 | 8 | from __future__ import annotations 9 | 10 | from typing import Any, Generic, TypeVar 11 | 12 | import inspect 13 | import os 14 | import urllib.parse 15 | from abc import ABC, abstractmethod 16 | 17 | from pydata_sphinx_theme.utils import ( # type: ignore[import-untyped] 18 | config_provided_by_user, 19 | ) 20 | from sphinx.application import Sphinx 21 | from sphinx.config import Config 22 | 23 | from rocm_docs import article_info 24 | 25 | T = TypeVar("T") 26 | 27 | 28 | class _ConfigUpdater(Generic[T], ABC): 29 | def __init__(self, default: T) -> None: 30 | super().__init__() 31 | self.default = default 32 | 33 | @abstractmethod 34 | def __call__(self, key: str, app: Sphinx) -> None: 35 | pass 36 | 37 | 38 | class _ConfigExtend(_ConfigUpdater[list[T]]): 39 | def __call__(self, key: str, app: Sphinx) -> None: 40 | getattr(app.config, key).extend(self.default) 41 | 42 | 43 | class _ConfigDefault(_ConfigUpdater[T]): 44 | def __call__(self, key: str, app: Sphinx) -> None: 45 | if not config_provided_by_user(app, key): 46 | setattr(app.config, key, self.default) 47 | 48 | 49 | class _ConfigUnion(_ConfigUpdater[set[T]]): 50 | def __call__(self, key: str, app: Sphinx) -> None: 51 | getattr(app.config, key).update(self.default) 52 | 53 | 54 | class _ConfigMerge(_ConfigUpdater[dict[str, Any]]): 55 | def __call__(self, key: str, app: Sphinx) -> None: 56 | current_setting: dict[str, Any] = getattr(app.config, key) 57 | for item in self.default.items(): 58 | current_setting.setdefault(item[0], item[1]) 59 | 60 | 61 | class _DefaultSettings: 62 | author = _ConfigDefault( 63 | 'Advanced Micro Devices Disclaimer and' 64 | " Licensing Info" 65 | ) 66 | # pylint: disable=redefined-builtin 67 | copyright = _ConfigDefault("2022-2023, Advanced Micro Devices Ltd") 68 | # pylint: enable=redefined-builtin 69 | myst_enable_extensions = _ConfigUnion( 70 | { 71 | "colon_fence", 72 | "dollarmath", 73 | "fieldlist", 74 | "html_image", 75 | "replacements", 76 | "substitution", 77 | } 78 | ) 79 | myst_heading_anchors = _ConfigDefault(3) 80 | external_toc_exclude_missing = _ConfigDefault(False) 81 | epub_show_urls = _ConfigDefault("footnote") 82 | exclude_patterns = _ConfigExtend(["_build", "Thumbs.db", ".DS_Store"]) 83 | numfig = _ConfigDefault(True) 84 | linkcheck_timeout = _ConfigDefault(10) 85 | linkcheck_request_headers = _ConfigMerge( 86 | { 87 | r"https://docs.github.com/": { 88 | "User-Agent": ( 89 | "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:112.0) " 90 | " Gecko/20100101 Firefox/112.0" 91 | ) 92 | } 93 | } 94 | ) 95 | 96 | @classmethod 97 | def update_config(cls, app: Sphinx, _: Config) -> None: 98 | """Update the Sphinx configuration from the default settings.""" 99 | for name, attr in inspect.getmembers(cls): 100 | if isinstance(attr, _ConfigUpdater): 101 | attr(name, app) 102 | 103 | 104 | def _force_notfound_prefix(app: Sphinx, _: Config) -> None: 105 | if "READTHEDOCS" not in os.environ: 106 | return 107 | 108 | if config_provided_by_user(app, "notfound_urls_prefix"): 109 | return 110 | 111 | components = urllib.parse.urlparse(os.environ["READTHEDOCS_CANONICAL_URL"]) 112 | app.config.notfound_urls_prefix = components.path 113 | 114 | 115 | def setup(app: Sphinx) -> dict[str, Any]: 116 | """Set up rocm_docs.core as a Sphinx extension.""" 117 | required_extensions = [ 118 | "myst_nb", 119 | "notfound.extension", 120 | "rocm_docs.projects", 121 | "sphinx_copybutton", 122 | "sphinx_design", 123 | "sphinx.ext.autodoc", 124 | "sphinx.ext.autosummary", 125 | "sphinx.ext.doctest", 126 | "sphinx.ext.duration", 127 | ] 128 | for ext in required_extensions: 129 | app.setup_extension(ext) 130 | 131 | app.add_config_value( 132 | "setting_all_article_info", default=False, rebuild="html", types=str 133 | ) 134 | app.add_config_value( 135 | "all_article_info_os", 136 | default=[], 137 | rebuild="html", 138 | types=str, 139 | ) 140 | app.add_config_value( 141 | "all_article_info_author", default="", rebuild="html", types=str 142 | ) 143 | app.add_config_value( 144 | "all_article_info_date", default="", rebuild="html", types=str 145 | ) 146 | app.add_config_value( 147 | "all_article_info_read_time", default="", rebuild="html", types=str 148 | ) 149 | app.add_config_value( 150 | "article_pages", default=[], rebuild="html", types=list 151 | ) 152 | 153 | # Run before notfound.extension sees the config (default priority(=500)) 154 | app.connect("config-inited", _force_notfound_prefix, priority=400) 155 | app.connect("config-inited", _DefaultSettings.update_config) 156 | app.connect("build-finished", article_info.set_article_info, priority=1000) 157 | return {"parallel_read_safe": True, "parallel_write_safe": True} 158 | -------------------------------------------------------------------------------- /src/rocm_docs/data/_doxygen/footer.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | -------------------------------------------------------------------------------- /src/rocm_docs/data/_doxygen/header.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | $projectname: $title 10 | $title 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | $treeview 20 | $search 21 | $mathjax 22 | 23 | $extrastylesheet 24 | 25 | 26 | 27 | 28 |
29 | 30 | 31 | 32 |
33 | -------------------------------------------------------------------------------- /src/rocm_docs/data/projects.schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-07/schema", 3 | "$id": "https://raw.githubusercontent.com/ROCm/rocm-docs-core/develop/src/rocm_docs/data/projects.schema.json", 4 | "$defs": { 5 | "doxygen": { 6 | "type": ["object", "string"], 7 | "description": "Relative path (from documentation root) to doxygen html folder", 8 | "properties": { 9 | "html": { 10 | "description": "Relative path (from documentation root) to doxygen html folder", 11 | "type": "string", 12 | "format": "uri-reference" 13 | } 14 | }, 15 | "required": ["html"] 16 | }, 17 | "project": { 18 | "title": "project", 19 | "description": "A single mapping for a project", 20 | "type": [ 21 | "object", 22 | "string" 23 | ], 24 | "properties": { 25 | "target": { 26 | "type": "string", 27 | "description": "Base URI of the sphinx documentation of the project", 28 | "default": "http://example.com" 29 | }, 30 | "inventory": { 31 | "default": null, 32 | "description": "Location of the inventory file", 33 | "type": [ 34 | "array", 35 | "string", 36 | "null" 37 | ], 38 | "uniqueItems": true, 39 | "items": { 40 | "type": [ 41 | "string", 42 | "null" 43 | ] 44 | } 45 | }, 46 | "development_branch": { 47 | "type": "string", 48 | "description": "Branch name of the \"development\" or \"mainline\" branch where development happens.", 49 | "default": "develop" 50 | }, 51 | "doxygen": { 52 | "$ref": "#/$defs/doxygen" 53 | } 54 | }, 55 | "required": [ 56 | "target" 57 | ] 58 | } 59 | }, 60 | "title": "External intersphinx mapping", 61 | "description": "Intersphinx mappings", 62 | "type": "object", 63 | "properties": { 64 | "version": { 65 | "type": "integer", 66 | "const": 1 67 | }, 68 | "projects": { 69 | "type": "object", 70 | "title": "projects", 71 | "description": "A mapping of project names to intersphinx targets", 72 | "default": { 73 | "projectname": "http://example.com" 74 | }, 75 | "propertyNames": { 76 | "pattern": "^[a-zA-Z][a-zA-Z0-9_\\-]*$" 77 | }, 78 | "patternProperties": { 79 | "^[a-zA-Z][a-zA-Z0-9_\\-]*$": { "$ref":"#/$defs/project" } 80 | }, 81 | "additionalProperties": false 82 | } 83 | }, 84 | "required": [ 85 | "version", 86 | "projects" 87 | ] 88 | } 89 | -------------------------------------------------------------------------------- /src/rocm_docs/data/projects.yaml: -------------------------------------------------------------------------------- 1 | # yaml-language-server: $schema=./projects.schema.json 2 | version: 1 3 | 4 | # ${version} will be replaced by the version of the (current) project in values 5 | projects: 6 | amdmigraphx: https://rocm.docs.amd.com/projects/AMDMIGraphX/en/${version} 7 | amdsmi: 8 | target: https://rocm.docs.amd.com/projects/amdsmi/en/${version} 9 | development_branch: amd-staging 10 | composable_kernel: https://rocm.docs.amd.com/projects/composable_kernel/en/${version} 11 | gpuaidev: 12 | target: https://rocm.docs.amd.com/projects/ai-developer-hub/en/${version} 13 | development_branch: main 14 | hip: 15 | target: https://rocm.docs.amd.com/projects/HIP/en/${version} 16 | development_branch: docs/develop 17 | hipblas: https://rocm.docs.amd.com/projects/hipBLAS/en/${version} 18 | hipblaslt: https://rocm.docs.amd.com/projects/hipBLASLt/en/${version} 19 | hipcc: 20 | target: https://rocm.docs.amd.com/projects/HIPCC/en/${version} 21 | development_branch: amd-staging 22 | hipcub: https://rocm.docs.amd.com/projects/hipCUB/en/${version} 23 | hipdf: https://rocm.docs.amd.com/projects/hipDF/en/${version} 24 | hipfft: https://rocm.docs.amd.com/projects/hipFFT/en/${version} 25 | hipfort: https://rocm.docs.amd.com/projects/hipfort/en/${version} 26 | hipgraph: 27 | target: https://rocm.docs.amd.com/projects/hipGRAPH/en/${version} 28 | development_branch: develop 29 | hipify: 30 | target: https://rocm.docs.amd.com/projects/HIPIFY/en/${version} 31 | development_branch: amd-staging 32 | hip-python: 33 | target: https://rocm.docs.amd.com/projects/hip-python/en/${version} 34 | development_branch: main 35 | hipmm: https://rocm.docs.amd.com/projects/hipMM/en/${version} 36 | hiprand: https://rocm.docs.amd.com/projects/hipRAND/en/${version} 37 | hipsolver: https://rocm.docs.amd.com/projects/hipSOLVER/en/${version} 38 | hipsparse: https://rocm.docs.amd.com/projects/hipSPARSE/en/${version} 39 | hipsparselt: https://rocm.docs.amd.com/projects/hipSPARSELt/en/${version} 40 | hiptensor: https://rocm.docs.amd.com/projects/hipTensor/en/${version} 41 | hip-vs: 42 | target: https://rocm.docs.amd.com/projects/hip-vs/en/${version} 43 | development_branch: master 44 | instinct: https://instinct.docs.amd.com/ 45 | llvm-project: https://rocm.docs.amd.com/projects/llvm-project/en/${version} 46 | miopen: https://rocm.docs.amd.com/projects/MIOpen/en/${version} 47 | mivisionx: https://rocm.docs.amd.com/projects/MIVisionX/en/${version} 48 | omniperf: 49 | target: https://rocm.docs.amd.com/projects/omniperf/en/${version} 50 | development_branch: amd-staging 51 | omnitrace: 52 | target: https://rocm.docs.amd.com/projects/omnitrace/en/${version} 53 | development_branch: amd-staging 54 | python: https://docs.python.org/3/ 55 | rccl: https://rocm.docs.amd.com/projects/rccl/en/${version} 56 | rdc: 57 | target: https://rocm.docs.amd.com/projects/rdc/en/${version} 58 | development_branch: amd-staging 59 | radeon: https://rocm.docs.amd.com/projects/radeon/en/${version} 60 | rocal: 61 | target: https://rocm.docs.amd.com/projects/rocAL/en/${version} 62 | development_branch: develop 63 | rocalution: https://rocm.docs.amd.com/projects/rocALUTION/en/${version} 64 | rocblas: https://rocm.docs.amd.com/projects/rocBLAS/en/${version} 65 | rocdbgapi: 66 | target: https://rocm.docs.amd.com/projects/ROCdbgapi/en/${version} 67 | development_branch: amd-staging 68 | rocdecode: 69 | target: https://rocm.docs.amd.com/projects/rocDecode/en/${version} 70 | development_branch: develop 71 | rocfft: https://rocm.docs.amd.com/projects/rocFFT/en/${version} 72 | rocgdb: 73 | target: https://rocm.docs.amd.com/projects/ROCgdb/en/${version} 74 | development_branch: amd-staging 75 | rocgraph: 76 | target: https://rocm.docs.amd.com/projects/rocGRAPH/en/${version} 77 | development_branch: develop 78 | rocjpeg: https://rocm.docs.amd.com/projects/rocJPEG/en/${version} 79 | rocm: https://rocm.docs.amd.com/en/${version} 80 | rocm-docs-core: https://rocm.docs.amd.com/projects/rocm-docs-core/en/${version} 81 | rocm-ds: 82 | target: https://rocm.docs.amd.com/projects/rocm-ds/en/${version} 83 | development_branch: develop 84 | rocm-ds-internal: 85 | target: https://rocm.docs.amd.com/projects/rocm-ds-internal/en/${version} 86 | development_branch: develop 87 | rocm-install-on-linux: 88 | target: https://rocm.docs.amd.com/projects/install-on-linux/en/${version} 89 | development_branch: develop 90 | rocm-install-on-windows: 91 | target: https://rocm.docs.amd.com/projects/install-on-windows/en/${version} 92 | development_branch: develop 93 | rocm_bandwidth_test: 94 | target: https://rocm.docs.amd.com/projects/rocm_bandwidth_test/en/${version} 95 | development_branch: master 96 | rocm_smi_lib: 97 | target: https://rocm.docs.amd.com/projects/rocm_smi_lib/en/${version} 98 | development_branch: amd-staging 99 | rocmcmakebuildtools: https://rocm.docs.amd.com/projects/ROCmCMakeBuildTools/en/${version} 100 | rocminfo: 101 | target: https://rocm.docs.amd.com/projects/rocminfo/en/${version} 102 | development_branch: amd-staging 103 | rocmvalidationsuite: 104 | target: https://rocm.docs.amd.com/projects/ROCmValidationSuite/en/${version} 105 | development_branch: master 106 | rocprim: https://rocm.docs.amd.com/projects/rocPRIM/en/${version} 107 | rocprof-compute-viewer: 108 | target: https://rocm.docs.amd.com/projects/rocprof-compute-viewer/en/${version} 109 | development_branch: amd-mainline 110 | rocprofiler: 111 | target: https://rocm.docs.amd.com/projects/rocprofiler/en/${version} 112 | development_branch: amd-master 113 | rocprofiler-compute: 114 | target: https://rocm.docs.amd.com/projects/rocprofiler-compute/en/${version} 115 | development_branch: amd-staging 116 | rocprofiler-sdk: 117 | target: https://rocm.docs.amd.com/projects/rocprofiler-sdk/en/${version} 118 | development_branch: amd-mainline 119 | rocprofiler-systems: 120 | target: https://rocm.docs.amd.com/projects/rocprofiler-systems/en/${version} 121 | development_branch: amd-staging 122 | rocpydecode: https://rocm.docs.amd.com/projects/rocPyDecode/en/${version} 123 | rocrand: https://rocm.docs.amd.com/projects/rocRAND/en/${version} 124 | rocr-runtime: 125 | target: https://rocm.docs.amd.com/projects/ROCR-Runtime/en/${version} 126 | development_branch: master 127 | rocr_debug_agent: 128 | target: https://rocm.docs.amd.com/projects/rocr_debug_agent/en/${version} 129 | development_branch: amd-staging 130 | rocshmem: 131 | target: https://rocm.docs.amd.com/projects/rocSHMEM/en/${version} 132 | development_branch: develop 133 | rocsolver: https://rocm.docs.amd.com/projects/rocSOLVER/en/${version} 134 | rocsparse: https://rocm.docs.amd.com/projects/rocSPARSE/en/${version} 135 | rocthrust: https://rocm.docs.amd.com/projects/rocThrust/en/${version} 136 | roctracer: 137 | target: https://rocm.docs.amd.com/projects/roctracer/en/${version} 138 | development_branch: amd-master 139 | rocwmma: https://rocm.docs.amd.com/projects/rocWMMA/en/${version} 140 | rpp: https://rocm.docs.amd.com/projects/rpp/en/${version} 141 | rtd: https://docs.readthedocs.io/en/stable/ 142 | sphinx: https://www.sphinx-doc.org/en/master/ 143 | tensile: https://rocm.docs.amd.com/projects/Tensile/en/${version} 144 | transferbench: https://rocm.docs.amd.com/projects/TransferBench/en/${version} 145 | -------------------------------------------------------------------------------- /src/rocm_docs/formatting.py: -------------------------------------------------------------------------------- 1 | """Utilities for formatting text.""" 2 | 3 | from __future__ import annotations 4 | 5 | from typing import Any 6 | 7 | import re 8 | from collections.abc import Generator, Iterable 9 | from dataclasses import dataclass 10 | from pathlib import Path 11 | 12 | 13 | class Formatter: 14 | """Formatting class for string substitution and comments parsing.""" 15 | 16 | @dataclass 17 | class _Replacement: 18 | loc: tuple[int, int] 19 | text: str 20 | 21 | def __init__(self, context: dict[str, Any]): 22 | """Initialize Formatter.""" 23 | self.directive_pattern: re.Pattern[str] = re.compile( 24 | r"(?P\$)?\{(?P[a-zA-z][a-zA-Z0-9_]+)" 25 | r"(?:\:(?P[a-zA-Z0-9_\-\.]+))?\}" 26 | ) 27 | self.context = context 28 | 29 | def _format_simple( 30 | self, directive: str, parameter: str | None, loc: tuple[int, int] 31 | ) -> _Replacement | None: 32 | # Cannot have a parameter 33 | if parameter is not None: 34 | return None 35 | return self._Replacement(loc, self.context[directive]) 36 | 37 | def _format_project( 38 | self, _: str, parameter: str | None, loc: tuple[int, int] 39 | ) -> _Replacement | None: 40 | # Parameter is required 41 | if parameter is None: 42 | return None 43 | if parameter not in self.context["projects"]: 44 | return None 45 | return self._Replacement(loc, self.context["projects"][parameter]) 46 | 47 | def _format_directive(self, match: re.Match[str]) -> _Replacement | None: 48 | # As a special case allow `{branch}` and `url` to alias `${branch}` 49 | # and '${url}' respectively for backwards compatibility. 50 | # Otherwise the '$' is required 51 | if match["prefix"] is None and match["directive"] not in [ 52 | "branch", 53 | "url", 54 | ]: 55 | return None 56 | 57 | if match["directive"] in ["branch", "url"]: 58 | return self._format_simple( 59 | match["directive"], match["parameter"], match.span() 60 | ) 61 | 62 | if match["directive"] == "project": 63 | return self._format_project( 64 | match["directive"], match["parameter"], match.span() 65 | ) 66 | 67 | return None 68 | 69 | def _replacements(self, line: str) -> Generator[_Replacement, None, None]: 70 | for match in self.directive_pattern.finditer(line): 71 | replacement = self._format_directive(match) 72 | if replacement is not None: 73 | yield replacement 74 | 75 | def format_line(self, line: str) -> str: 76 | """Substitute variable references into line. 77 | 78 | References of the form ${} and ${directive:param} 79 | are substituted 80 | >>> f = Formatter( 81 | ... { 82 | ... "branch": "develop", 83 | ... "url": "https://example.com", 84 | ... "projects": {"project": "https://project.com"}, 85 | ... } 86 | ... ) 87 | >>> f.format_line('my branch is ${branch}, {branch} also works') 88 | 'my branch is develop, develop also works' 89 | >>> f.format_line('Url: ${url} or {url}') 90 | 'Url: https://example.com or https://example.com' 91 | >>> f.format_line('- url: ${project:project}') 92 | '- url: https://project.com' 93 | 94 | Unknown references are not replaced. 95 | >>> f.format_line('{invalid}') 96 | '{invalid}' 97 | """ 98 | result: str = "" 99 | end: int = 0 100 | for replacement in self._replacements(line): 101 | assert replacement.loc[0] >= end 102 | result += line[end : replacement.loc[0]] + replacement.text 103 | end = replacement.loc[1] 104 | 105 | result += line[end:] 106 | return result 107 | 108 | def skip_comments(self, lines: Iterable[str]) -> Generator[str, None, None]: 109 | """Returns a sequence that skips lines as long as they start with '#'. 110 | 111 | Lines after the first "non-comment" line are returned as-is. 112 | >>> f = Formatter({}) 113 | >>> for l in f.skip_comments( 114 | ... ["#comment 0", "# comment 1", "text", "# will not be skipped"] 115 | ... ): 116 | ... print(l) 117 | text 118 | # will not be skipped 119 | """ 120 | iterator = iter(lines) 121 | for line in iterator: 122 | if not line.startswith("#"): 123 | yield line 124 | break 125 | yield from iterator 126 | 127 | 128 | def format_toc( 129 | input_path: Path, output_path: Path, context: dict[str, Any] 130 | ) -> None: 131 | """Format the input table of contents with additional information.""" 132 | formatter = Formatter(context) 133 | with ( 134 | open(input_path, encoding="utf-8") as toc_in, 135 | open(output_path, "w", encoding="utf-8") as toc_out, 136 | ): 137 | for line in formatter.skip_comments(toc_in): 138 | toc_out.write(formatter.format_line(line)) 139 | -------------------------------------------------------------------------------- /src/rocm_docs/py.typed: -------------------------------------------------------------------------------- 1 | # Marker file for PEP 561. This package uses inline types. 2 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/404.html: -------------------------------------------------------------------------------- 1 | {%- extends "page.html" %} 2 | {% block body %} 3 |

404 - Page Not Found

4 |

Use the navigation bar on the side to get back on track.

5 | {% endblock %} 6 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/components/article-info.html: -------------------------------------------------------------------------------- 1 |
2 |
3 |
4 |
5 |
6 |
7 |

8 | 9 | 12 | 13 | 14 |

15 |
16 |
17 |

18 | 19 | 22 | 23 | 24 |

25 |
26 |
27 | 28 |
29 |
30 |

31 |
32 |
33 |
34 |
35 |
36 |
37 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/components/left-side-menu.html: -------------------------------------------------------------------------------- 1 | {% 2 | from "flavors/" ~ theme_flavor ~ "/left-side-menu.jinja" import 3 | main_doc_link 4 | with context 5 | %} 6 | {% set text, target = main_doc_link %} 7 | 10 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/components/toggle-primary-sidebar.html: -------------------------------------------------------------------------------- 1 | 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/ai-developer-hub/footer.jinja: -------------------------------------------------------------------------------- 1 | {% macro license_link() -%}{%- endmacro -%} 2 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/ai-developer-hub/header.jinja: -------------------------------------------------------------------------------- 1 | {% macro top_level_header(branch, latest_version, release_candidate_version) -%} 2 | {% if branch in ["develop", "master", "main", "amd-master", "amd-staging"] %} 3 | {% set version_name = "Future Release" %} 4 | {% elif branch == "latest" %} 5 | {% set version_name = "" %} 6 | {% else %} 7 | {% set version_name = branch %} 8 | {% endif %} 9 | AI Tutorials {{ version_name }} 10 | {%- endmacro -%} 11 | 12 | {% if theme_repository_url.endswith("-docs") %} 13 | {% set repo_url = theme_repository_url|replace("-docs", "") %} 14 | {% else %} 15 | {% set repo_url = theme_repository_url %} 16 | {% endif %} 17 | 18 | {% set repo_url = repo_url|replace("http://", "https://") %} 19 | 20 | {% macro version_list() -%} 21 | Version List 22 | {%- endmacro -%} 23 | 24 | {% 25 | set nav_secondary_items = { 26 | "GitHub": repo_url, 27 | "Community": "https://github.com/ROCm/ROCm/discussions", 28 | "Blogs": "https://rocm.blogs.amd.com/", 29 | "ROCm™ Docs": "https://rocm.docs.amd.com", 30 | "ROCm Developer Hub": "https://www.amd.com/en/developer/resources/rocm-hub.html", 31 | "Instinct™ Docs": "https://instinct.docs.amd.com", 32 | "Infinity Hub": "https://www.amd.com/en/developer/resources/infinity-hub.html", 33 | "Support": repo_url + "/issues/new/choose" 34 | } 35 | %} 36 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/ai-developer-hub/left-side-menu.jinja: -------------------------------------------------------------------------------- 1 | {% 2 | set main_doc_link = ("AI Developer", projects['gpuaidev']) 3 | %} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/generic/footer.jinja: -------------------------------------------------------------------------------- 1 | {% macro license_link() -%} 2 | {% if theme_license_link %} 3 |
  • {{ theme_license_text if theme_license_text else "" }}
    • 4 | {% endif %} 5 | {%- endmacro -%} 6 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/generic/header.jinja: -------------------------------------------------------------------------------- 1 | {% macro top_level_header(branch, latest_version, release_candidate_version) -%} 2 | {% if theme_header_title %} 3 | {% set header_title = theme_header_title %} 4 | {% else %} 5 | {% set header_title = project ~ " " ~ version %} 6 | {% endif %} 7 | 8 | {% if theme_header_link %} 9 | {% set header_link = theme_header_link %} 10 | {% else %} 11 | {% set header_link = "#" %} 12 | {% endif %} 13 | 14 | {{ header_title }} 15 | {%- endmacro -%} 16 | 17 | {% macro version_list() -%} 18 | {% if theme_version_list_link %} 19 | Version List 20 | {% endif %} 21 | {%- endmacro -%} 22 | 23 | {% 24 | set nav_secondary_items = theme_nav_secondary_items if theme_nav_secondary_items else { 25 | "GitHub": theme_repository_url if theme_repository_url else "#", 26 | "Support": (theme_repository_url + "/issues/new/choose") if theme_repository_url else "#" 27 | } 28 | %} 29 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/generic/left-side-menu.jinja: -------------------------------------------------------------------------------- 1 | {% 2 | set main_doc_link = theme_main_doc_link if theme_main_doc_link else (project, "#") 3 | %} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/instinct/footer.jinja: -------------------------------------------------------------------------------- 1 | {% macro license_link() -%}{%- endmacro -%} 2 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/instinct/header.jinja: -------------------------------------------------------------------------------- 1 | {% macro top_level_header(branch, latest_version, release_candidate_version) -%} 2 | {% if branch in ["develop", "master", "main", "amd-master", "amd-staging"] %} 3 | {% set version_name = "Future Release" %} 4 | {% elif branch == "latest" %} 5 | {% set version_name = latest_version %} 6 | {% else %} 7 | {% set version_name = branch %} 8 | {% endif %} 9 | Instinct™ Documentation 10 | {%- endmacro -%} 11 | 12 | 13 | {% set repo_url = repo_url|replace("http://", "https://") %} 14 | 15 | {% macro version_list() -%} 16 | {% if theme_version_list_link %} 17 | Version List 18 | {% endif %} 19 | {%- endmacro -%} 20 | 21 | {% 22 | set nav_secondary_items = theme_nav_secondary_items if theme_nav_secondary_items else { 23 | "GitHub": theme_repository_url if theme_repository_url else "#", 24 | "Community": "https://github.com/ROCm/ROCm/discussions", 25 | "Blogs": "https://rocm.blogs.amd.com/", 26 | "ROCm Developer Hub": "https://www.amd.com/en/developer/resources/rocm-hub.html", 27 | "ROCm™ Docs": "https://rocm.docs.amd.com", 28 | "Support": (theme_repository_url + "/issues/new/choose") if theme_repository_url else "#" 29 | } 30 | %} 31 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/instinct/left-side-menu.jinja: -------------------------------------------------------------------------------- 1 | {% 2 | set main_doc_link = ("Instinct Documentation", projects['instinct']) 3 | %} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-blogs/footer.jinja: -------------------------------------------------------------------------------- 1 | {% macro license_link() -%}{%- endmacro -%} 2 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-blogs/header.jinja: -------------------------------------------------------------------------------- 1 | {% macro top_level_header(branch, latest_version, release_candidate_version) -%} 2 | ROCm™ Blogs 3 | {%- endmacro -%} 4 | 5 | {% macro version_list() -%}{%- endmacro -%} 6 | 7 | {% 8 | set repo_url = theme_repository_url|replace("-internal", "") 9 | %} 10 | {% set repo_url = repo_url|replace("http://", "https://") %} 11 | {% 12 | set nav_secondary_items = { 13 | "GitHub": repo_url, 14 | "Community": "https://github.com/ROCm/ROCm/discussions", 15 | "ROCm™ Docs": "https://rocm.docs.amd.com", 16 | "ROCm Developer Hub": "https://www.amd.com/en/developer/resources/rocm-hub.html", 17 | "Instinct™ Docs": "https://instinct.docs.amd.com", 18 | "Support": repo_url + "/issues/new/choose" 19 | } 20 | %} 21 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-blogs/left-side-menu.jinja: -------------------------------------------------------------------------------- 1 | {% 2 | set main_doc_link = ("ROCm blogs", "https://rocm.blogs.amd.com/") 3 | %} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-docs-home/footer.jinja: -------------------------------------------------------------------------------- 1 | ../rocm/footer.jinja -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-docs-home/header.jinja: -------------------------------------------------------------------------------- 1 | ../rocm/header.jinja -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-docs-home/left-side-menu.jinja: -------------------------------------------------------------------------------- 1 | {% 2 | set main_doc_link = ("ROCm documentation", projects['rocm']) 3 | %} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-ds/footer.jinja: -------------------------------------------------------------------------------- 1 | {% macro license_link() -%}{%- endmacro -%} 2 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-ds/header.jinja: -------------------------------------------------------------------------------- 1 | {% macro top_level_header(branch, latest_version, release_candidate_version) -%} 2 | {% if branch in ["develop", "master", "main", "amd-master", "amd-staging"] %} 3 | {% set version_name = "Future Release" %} 4 | {% elif branch == "latest" %} 5 | {% set version_name = "25.05" %} 6 | {% else %} 7 | {% set version_name = branch %} 8 | {% endif %} 9 | ROCm Data Science {{ version_name }} 10 | {%- endmacro -%} 11 | 12 | {% if theme_repository_url.endswith("-docs") %} 13 | {% set repo_url = theme_repository_url|replace("-docs", "") %} 14 | {% else %} 15 | {% set repo_url = theme_repository_url %} 16 | {% endif %} 17 | 18 | {% set repo_url = repo_url|replace("http://", "https://") %} 19 | 20 | {% macro version_list() -%} 21 | {% if theme_version_list_link %} 22 | Version List 23 | {% endif %} 24 | {%- endmacro -%} 25 | 26 | {% 27 | set nav_secondary_items = { 28 | "GitHub": repo_url, 29 | "Community": "https://github.com/ROCm/ROCm/discussions", 30 | "Blogs": "https://rocm.blogs.amd.com/", 31 | "ROCm™ Docs": "https://rocm.docs.amd.com", 32 | "ROCm Developer Hub": "https://www.amd.com/en/developer/resources/rocm-hub.html", 33 | "Instinct™ Docs": "https://instinct.docs.amd.com", 34 | "Infinity Hub": "https://www.amd.com/en/developer/resources/infinity-hub.html", 35 | "Support": repo_url + "/issues/new/choose" 36 | } 37 | %} 38 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm-ds/left-side-menu.jinja: -------------------------------------------------------------------------------- 1 | {% 2 | set main_doc_link = ("ROCm Data Science", projects['rocm-ds']) 3 | %} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm/footer.jinja: -------------------------------------------------------------------------------- 1 | {% macro license_link() -%} 2 |
  • ROCm Licenses and Disclaimers
    • 3 | {%- endmacro -%} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm/header.jinja: -------------------------------------------------------------------------------- 1 | {% macro top_level_header(branch, latest_version, release_candidate_version) -%} 2 | {% if branch in ["develop", "master", "main", "amd-master", "amd-staging"] %} 3 | {% set version_name = "Future Release" %} 4 | {% elif branch == "latest" %} 5 | {% set version_name = latest_version %} 6 | {% else %} 7 | {% set version_name = branch %} 8 | {% endif %} 9 | ROCm™ Software {{ version_name }} 10 | {%- endmacro -%} 11 | 12 | {% macro version_list() -%} 13 | Version List 14 | {%- endmacro -%} 15 | 16 | {% if theme_repository_url.endswith("-docs") %} 17 | {% set repo_url = theme_repository_url|replace("-docs", "") %} 18 | {% else %} 19 | {% set repo_url = theme_repository_url %} 20 | {% endif %} 21 | 22 | {% set repo_url = repo_url|replace("http://", "https://") %} 23 | 24 | {% 25 | set nav_secondary_items = { 26 | "GitHub": repo_url, 27 | "Community": "https://github.com/ROCm/ROCm/discussions", 28 | "Blogs": "https://rocm.blogs.amd.com/", 29 | "ROCm Developer Hub": "https://www.amd.com/en/developer/resources/rocm-hub.html", 30 | "Instinct™ Docs": "https://instinct.docs.amd.com", 31 | "Infinity Hub": "https://www.amd.com/en/developer/resources/infinity-hub.html", 32 | "Support": repo_url + "/issues/new/choose" 33 | } 34 | %} 35 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm/left-side-menu.jinja: -------------------------------------------------------------------------------- 1 | {% 2 | set main_doc_link = ("ROCm documentation", projects['rocm']) 3 | %} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/flavors/rocm/meta.jinja: -------------------------------------------------------------------------------- 1 | {% macro google_site_verification(google_site_verification_content) -%} 2 | 3 | {%- endmacro -%} 4 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/layout.html: -------------------------------------------------------------------------------- 1 | {% extends "sphinx_book_theme/layout.html" %} 2 | 3 | {% block extrahead %} 4 | 5 | {% endblock %} 6 | 7 | {% block docs_navbar %} 8 | {%- include "sections/header.html" %} 9 | {% endblock %} 10 | 11 | {%- block footer %} 12 | {%- include "sections/footer.html" %} 13 | {%- endblock %} 14 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/sections/footer-content.html: -------------------------------------------------------------------------------- 1 |

    2 | {%- if last_updated %} 3 | {% trans prefix=translate('Last updated on'), last_updated=last_updated|e %}{{ prefix }} {{ last_updated }}.{% endtrans %}
    4 | {%- endif %} 5 | {%- if theme_extra_footer %} 6 |

    7 | {{ theme_extra_footer }} 8 |
    9 | {%- endif %} 10 |

    11 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/sections/footer.html: -------------------------------------------------------------------------------- 1 | {% 2 | from "flavors/" ~ theme_flavor ~ "/footer.jinja" import 3 | license_link 4 | with context 5 | %} 6 | 36 | 37 | 40 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/sections/header.html: -------------------------------------------------------------------------------- 1 | {% 2 | from "flavors/" ~ theme_flavor ~ "/header.jinja" import 3 | nav_secondary_items, top_level_header, version_list 4 | with context 5 | %} 6 | 7 |
    8 | 33 | {% if nav_secondary_items %} 34 | 49 | {% endif %} 50 |
    51 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/sections/meta.html: -------------------------------------------------------------------------------- 1 | {% 2 | from "flavors/" ~ theme_flavor ~ "/meta.jinja" import 3 | google_site_verification 4 | with context 5 | %} 6 | 7 | {{ google_site_verification(google_site_verification_content) }} 8 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/code_word_breaks.js: -------------------------------------------------------------------------------- 1 | $(document).ready(() => { 2 | const copy = async(event) => { 3 | return await navigator.clipboard.writeText($(event.target).attr('copydata')); 4 | } 5 | 6 | $('.table td code').each( function () { 7 | var text = $(this).text() 8 | $(this).addClass('hovertext') 9 | $(this).attr('copydata', text) 10 | $(this).attr('data-hover', "Click to copy.") 11 | var new_text = text.replaceAll(/_([^\u200B])/g, '_\u200B$1').replaceAll(/([a-z])([A-Z])/g, '$1\u200B$2') 12 | $(this).text(new_text) 13 | $(this).click((event) => { 14 | copy(event) 15 | $(event.target).attr('data-hover', "Copied!") 16 | $(event.target).on("mouseleave", () => { 17 | $(event.target).attr('data-hover', "Click to copy.") 18 | $(event.target).off("mouseleave") 19 | }) 20 | }) 21 | }) 22 | }) 23 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/custom.css: -------------------------------------------------------------------------------- 1 | :root { 2 | --pst-font-size-base: 0.875rem; 3 | } 4 | 5 | @media screen and (min-width: 440px) { 6 | :root { 7 | --pst-font-size-base: 1rem; 8 | } 9 | } 10 | 11 | @media screen and (min-width: 2000px) { 12 | :root { 13 | --pst-font-size-base: 1.25rem; 14 | } 15 | } 16 | 17 | .mx-40 { 18 | margin-left: 1rem !important; 19 | margin-right: 1rem !important; 20 | } 21 | 22 | .my-25 { 23 | margin-top: 0.25rem !important; 24 | margin-bottom: 0.25rem !important; 25 | } 26 | 27 | .py-45 { 28 | padding-bottom: 1.625rem !important; 29 | padding-top: 1.625rem !important; 30 | } 31 | 32 | .hover-opacity { 33 | transition: 0.28s; 34 | } 35 | 36 | .hover-opacity:hover { 37 | opacity: 0.7; 38 | } 39 | 40 | .klavika-font { 41 | font-family: Klavika, arial, sans-serif; 42 | font-size: 1.375rem; 43 | } 44 | 45 | /* for the light theme */ 46 | html[data-theme="light"] { 47 | --link-color: #0051c6; 48 | } 49 | 50 | /* for the dark theme */ 51 | html[data-theme="dark"] { 52 | --link-color: #2899ff; 53 | .line{ 54 | color: #fff; 55 | }; 56 | } 57 | 58 | div#site-navigation { 59 | height: fit-content; 60 | min-height: calc(100vh - 190px); 61 | } 62 | 63 | div.content-container { 64 | overflow-y: clip; 65 | } 66 | 67 | .hovertext { 68 | position: relative; 69 | /* border-bottom: 1px dotted black; */ 70 | } 71 | 72 | .hovertext:before { 73 | content: attr(data-hover); 74 | visibility: hidden; 75 | opacity: 0; 76 | width: 140px; 77 | background-color: black; 78 | color: #fff; 79 | text-align: center; 80 | border-radius: 5px; 81 | padding: 5px 0; 82 | transition: opacity 0.5s ease-in-out; 83 | 84 | position: absolute; 85 | z-index: 1; 86 | left: 0; 87 | top: 110%; 88 | } 89 | 90 | .hovertext:hover:before { 91 | opacity: 1; 92 | visibility: visible; 93 | } 94 | 95 | div#rdc-watermark-container { 96 | pointer-events: none; 97 | position: fixed; 98 | height: 100vh; 99 | width: 100vw; 100 | top: 0; 101 | left: 0; 102 | z-index: 2000; 103 | } 104 | 105 | img#rdc-watermark { 106 | pointer-events: none; 107 | position: absolute; 108 | top: 50%; 109 | left: 50%; 110 | transform-origin: center; 111 | transform: translate(-50%, -50%) rotate(-45deg); 112 | opacity: 10%; 113 | z-index: 2000; 114 | max-width: 100%; 115 | max-height: calc(100% - 200px); 116 | object-fit: contain; 117 | width: 45%; 118 | opacity: 20%; 119 | } 120 | 121 | ul.bd-breadcrumbs { 122 | margin-bottom: 0; 123 | margin-top: 1px; 124 | margin-left: 1rem; 125 | } 126 | 127 | ul.bd-breadcrumbs li.breadcrumb-item { 128 | align-items: baseline; 129 | align-self: baseline; 130 | } 131 | 132 | .bd-sidebar-primary { 133 | top: 3.5rem; 134 | height: calc(100vh - 3.5rem); 135 | } 136 | 137 | .sbt-scroll-pixel-helper { 138 | top: 3.5rem !important; 139 | } 140 | 141 | @media (min-width: 576px) and (max-width: 959.98px) { 142 | .bd-sidebar-primary { 143 | top: 5.5rem; 144 | height: calc(100vh - 5.5rem); 145 | } 146 | } 147 | 148 | @media(min-width: 960px) { 149 | .bd-sidebar-primary { 150 | top: 0; 151 | height: 100vh; 152 | } 153 | } 154 | 155 | @media(min-width: 576px) { 156 | .sbt-scroll-pixel-helper { 157 | top: 5.5rem !important; 158 | } 159 | } 160 | 161 | @media(min-width: 1200px) { 162 | .sbt-scroll-pixel-helper { 163 | top: 9.5rem !important; 164 | } 165 | } 166 | 167 | .bd-sidebar-primary .sidebar-header-items { 168 | display: flex; 169 | flex-direction: column; 170 | } 171 | 172 | .bd-container .primary-toggle>span { 173 | transform-origin: 50%, 50%; 174 | transition: transform 0.3s ease-in-out; 175 | transform: rotate(0); 176 | } 177 | 178 | input#__primary:checked ~ .bd-container .primary-toggle>span { 179 | transform: rotate(180deg); 180 | } 181 | 182 | a#ot-sdk-btn { 183 | background: none !important; 184 | border: none !important; 185 | padding: 0 !important; 186 | color: #9d9fa2 !important; 187 | } 188 | 189 | .bd-sidebar-primary.bd-sidebar.noprint { 190 | gap: 0px !important; 191 | } 192 | 193 | .navbar-brand.logo { 194 | align-items: flex-start !important; 195 | padding: 0px !important; 196 | font-size: 1rem !important; 197 | } 198 | 199 | .navbar-brand .logo__title { 200 | text-align: left !important; 201 | } 202 | 203 | /* Fix for sidebar width mismatch between Bootstrap and the Sphinx Book Theme */ 204 | @media (min-width: 960px) { 205 | input#__primary:checked ~ .bd-container .bd-sidebar-primary { 206 | margin-left: -20%; 207 | visibility: hidden; 208 | opacity: 0; 209 | } 210 | .bd-sidebar-primary { 211 | flex-basis: 20%; 212 | } 213 | 214 | .bd-container .primary-toggle>span { 215 | transform: rotate(180deg); 216 | } 217 | 218 | input#__primary:checked ~ .bd-container .primary-toggle>span { 219 | transform: rotate(0); 220 | } 221 | } 222 | 223 | .bd-sidebar-secondary { 224 | /* Header z-index is 2000, flyout z-index is 3000. 225 | * Setting sidebar's z-index to be between 2000 and 3000 to hover over the header without covering the flyout. */ 226 | z-index: 2001; 227 | } 228 | 229 | .sd-card-body.rocm-card-banner { 230 | padding-top: 0; 231 | padding-left: 0; 232 | padding-right: 0; 233 | } 234 | 235 | .sd-card-body.rocm-card-banner>* { 236 | margin-left: 1rem; 237 | margin-right: 1rem; 238 | --rocm-color-card-banner-bg: 0 0 0; 239 | --rocm-color-card-banner-text: white; 240 | } 241 | 242 | .sd-card-body.rocm-card-banner .sd-card-title { 243 | margin: 0 0 0 0; 244 | padding: 1rem 1rem 1rem; 245 | font-family: sans-serif; 246 | background-color: var(--rocm-color-card-banner-bg); 247 | background-image: linear-gradient(to right, 248 | rgb(var(--rocm-color-card-banner-bg) / 80%) 1rem, 249 | rgb(var(--rocm-color-card-banner-bg) / 15%) 10rem, 250 | transparent 16rem), 251 | linear-gradient(to top, 252 | transparent, 253 | rgb(var(--rocm-color-card-banner-bg) / 20%) 25% 60%, 254 | transparent), 255 | url(images/banner-violet.jpg); 256 | background-size: cover; 257 | background-position: bottom left; 258 | color: var(--rocm-color-card-banner-text); 259 | } 260 | 261 | .sd-card-body.rocm-card-banner .sd-card-title * { 262 | color: var(--rocm-color-card-banner-text); 263 | } 264 | 265 | .sd-card-body.rocm-card-banner>.sd-card-title a:hover { 266 | color: var(--rocm-color-card-banner-text); 267 | } 268 | 269 | /* Hue rotation classes */ 270 | /* .rocm-hue-1 doesn't apply any transform */ 271 | 272 | .sd-card-body.rocm-hue-2 .sd-card-title { 273 | filter: hue-rotate(-50deg); 274 | } 275 | 276 | .sd-card-body.rocm-hue-3 .sd-card-title { 277 | filter: hue-rotate(-75deg); 278 | } 279 | 280 | .sd-card-body.rocm-hue-4 .sd-card-title { 281 | filter: hue-rotate(-100deg); 282 | } 283 | 284 | .sd-card-body.rocm-hue-5 .sd-card-title { 285 | filter: hue-rotate(-125deg); 286 | } 287 | 288 | .sd-card-body.rocm-hue-6 .sd-card-title { 289 | filter: hue-rotate(-150deg); 290 | } 291 | 292 | .sd-card-body.rocm-hue-7 .sd-card-title { 293 | filter: hue-rotate(-175deg); 294 | } 295 | 296 | .sd-card-body.rocm-hue-8 .sd-card-title { 297 | filter: hue-rotate(-200deg); 298 | } 299 | 300 | .sd-card-body.rocm-hue-9 .sd-card-title { 301 | filter: hue-rotate(-225deg); 302 | } 303 | 304 | .sd-card-body.rocm-hue-10 .sd-card-title { 305 | filter: hue-rotate(-250deg); 306 | } 307 | 308 | .sd-card-body.rocm-hue-11 .sd-card-title { 309 | filter: hue-rotate(-275deg); 310 | } 311 | 312 | .sd-card-body.rocm-hue-12 .sd-card-title { 313 | filter: hue-rotate(-300deg); 314 | } 315 | 316 | :not(p) img { 317 | margin-bottom: 1rem; 318 | } 319 | 320 | #rocm-banner { 321 | color: #80dfff; 322 | } 323 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts.css.map: -------------------------------------------------------------------------------- 1 | { 2 | "version": 3, 3 | "mappings": "AAsDM,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCG,GAAG;EAuCjB,GAAG,EAAE,mJACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCQ,GAAG;EAuCtB,GAAG,EAAE,2JACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCa,GAAG;EAuC3B,GAAG,EAAE,mJACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCkB,GAAG;EAuChC,GAAG,EAAE,mJACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCuB,GAAG;EAuCrC,GAAG,EAAE,mJACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtC4B,GAAG;EAuC1C,GAAG,EAAE,mJACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCG,GAAG;EAuCjB,GAAG,EAAE,+JACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCQ,GAAG;EAuCtB,GAAG,EAAE,yJACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCa,GAAG;EAuC3B,GAAG,EAAE,+JACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCkB,GAAG;EAuChC,GAAG,EAAE,+JACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCuB,GAAG;EAuCrC,GAAG,EAAE,+JACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtC4B,GAAG;EAuC1C,GAAG,EAAE,+JACmC;EACxC,aAAa,EAvCC,qJAiBR;AAeR,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCG,GAAG;EAuCjB,GAAG,EAAE,2JACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCQ,GAAG;EAuCtB,GAAG,EAAE,mKACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCa,GAAG;EAuC3B,GAAG,EAAE,2JACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCkB,GAAG;EAuChC,GAAG,EAAE,2JACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCuB,GAAG;EAuCrC,GAAG,EAAE,2JACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtC4B,GAAG;EAuC1C,GAAG,EAAE,2JACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCG,GAAG;EAuCjB,GAAG,EAAE,uKACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCQ,GAAG;EAuCtB,GAAG,EAAE,iKACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCa,GAAG;EAuC3B,GAAG,EAAE,uKACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCkB,GAAG;EAuChC,GAAG,EAAE,uKACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtCuB,GAAG;EAuCrC,GAAG,EAAE,uKACmC;EACxC,aAAa,EAnBG,+FASH;AAGf,UAQC;EAPC,YAAY,EAAE,IAAI;EAClB,WAAW,EAAE,SAAS;EACtB,UAAU,EAAE,MAAe;EAC3B,WAAW,EAtC4B,GAAG;EAuC1C,GAAG,EAAE,uKACmC;EACxC,aAAa,EAnBG,+FASH", 4 | "sources": ["fonts.scss"], 5 | "names": [], 6 | "file": "fonts.css" 7 | } 8 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts.scss: -------------------------------------------------------------------------------- 1 | @function fontPath($weight, $style, $ext: false) { 2 | $result: "./fonts/open-sans/open-sans-v34-latin-"; 3 | @if $ext { 4 | $result: $result + "ext-"; 5 | } 6 | @if $weight == 400 { 7 | @if $style == "normal" { 8 | $result: $result + "regular"; 9 | } 10 | } @else { 11 | $result: $result + $weight; 12 | } 13 | @if $style != "normal" { 14 | $result: $result + $style; 15 | } 16 | @return $result + ".woff"; 17 | } 18 | 19 | @each $ext in (false, true) { 20 | @each $style in ("normal", "italic") { 21 | @each $weight in (300, 400, 500, 600, 700, 800) { 22 | $fontPath: fontPath($weight, $style, $ext); 23 | $unicodeRange: ( 24 | u+00??, 25 | u+0131, 26 | u+0152-0153, 27 | u+02bb-02bc, 28 | u+02c6, 29 | u+02da, 30 | u+02dc, 31 | u+2000-206f, 32 | u+2074, 33 | u+20ac, 34 | u+2122, 35 | u+2191, 36 | u+2193, 37 | u+2212, 38 | u+2215, 39 | u+feff, 40 | u+fffd 41 | ); 42 | @if $ext { 43 | $unicodeRange: ( 44 | u+0100-024f, 45 | u+0259, 46 | u+1e??, 47 | u+2020, 48 | u+20a0-20ab, 49 | u+20ad-20cf, 50 | u+2113, 51 | u+2c60-2c7f, 52 | u+a720-a7ff 53 | ); 54 | } 55 | @font-face { 56 | font-display: swap; 57 | font-family: Open Sans; 58 | font-style: unquote($style); 59 | font-weight: $weight; 60 | src: local(""), url(unquote($fontPath + "2")) format("woff2"), 61 | url(unquote($fontPath)) format("woff"); 62 | unicode-range: $unicodeRange; 63 | } 64 | $fontPath: fontPath($weight, $style, true); 65 | } 66 | } 67 | } 68 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-300italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-500italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-600italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-700italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-800italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-300italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-500italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-600italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-700italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-800italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-regular.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-ext-regular.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-italic.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-italic.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-regular.woff -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/fonts/open-sans/open-sans-v34-latin-regular.woff2 -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/images/alpha-watermark.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 7 | 8 | 10 | 15 | 17 | 21 | 24 | 29 | 30 | 31 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/images/amd-header-logo.svg: -------------------------------------------------------------------------------- 1 | AMD-logo-white-v2 2 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/images/banner-violet.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/images/banner-violet.jpg -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/images/beta-watermark.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/images/rocm-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ROCm/rocm-docs-core/a1c1caf1b6268b28db0d36741f9153572d2f3847/src/rocm_docs/rocm_docs_theme/static/images/rocm-logo.png -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/rdcMisc.js: -------------------------------------------------------------------------------- 1 | function fixBreadcrumbItems() { 2 | const breadcrumbItems = $("li.breadcrumb-item:not(.breadcrumb-home,.active)"); 3 | const breadcrumbBox = $("ul.bd-breadcrumbs") 4 | breadcrumbBox.data("maxWidth", 0) 5 | function adjustLength(item, container, factor, getTextItem) { 6 | const textItem = getTextItem(item); 7 | const lines = (x) => Math.round(x.height() / parseFloat(x.css('line-height').replace('px', ''))) 8 | function getMaxWidth(container, itm) { 9 | const startLines = lines(container); 10 | const initialText = itm.text(); 11 | let maxWidth = container.width(); 12 | while (lines(container) == startLines) { 13 | itm.text(itm.text() + "\u200B."); 14 | if (container.width() > maxWidth) { 15 | maxWidth = container.width() 16 | } 17 | } 18 | itm.text(initialText); 19 | return maxWidth; 20 | } 21 | const containerMaxWidth = container.data("maxWidth") || getMaxWidth(container, textItem); 22 | container.data("maxWidth", containerMaxWidth) 23 | const fullText = item.data("fullText") || textItem.text(); 24 | item.data("fullText", fullText); 25 | textItem.text(fullText) 26 | if (lines(item) == 1 && item.width() < containerMaxWidth * factor) { 27 | return; 28 | } 29 | const words = fullText.split(/\s/); 30 | let newText = words[0]; 31 | for (let i = 1; i < words.length; i++) { 32 | textItem.text(newText + " " + words[i] + "..."); 33 | if (lines(item) == 1 && item.width() < containerMaxWidth * factor) { 34 | newText += " " + words[i]; 35 | } else { 36 | break; 37 | } 38 | } 39 | newText += "..."; 40 | textItem.text(newText); 41 | } 42 | breadcrumbItems.each(function () { 43 | adjustLength($(this), breadcrumbBox, 0.82 * (breadcrumbItems.length <= 2 ? 1 : 0.5), x => x.children('a')) 44 | }) 45 | adjustLength($("li.breadcrumb-item.active"), breadcrumbBox, 0.95, x => x); 46 | breadcrumbBox.data("maxWidth", 0); 47 | } 48 | 49 | $(document).ready(function () { 50 | if (window.ResizeObserver) { 51 | document.body.addEventListener("bodyresize", event => { 52 | const { contentRect } = event.detail; 53 | const { width } = contentRect; 54 | if (window.prevWidth) { 55 | 56 | } 57 | if ((window.prevWidth && window.prevWidth > 960) && width < 960) { 58 | $("input#__primary").prop("checked", false); 59 | } 60 | window.prevWidth = width; 61 | fixBreadcrumbItems(); 62 | }) 63 | 64 | const onResizeCallback = (() => { 65 | let initial = true; 66 | let timeout; 67 | return entries => { 68 | if (initial) { 69 | initial = false; 70 | return; 71 | } 72 | clearTimeout(timeout) 73 | timeout = setTimeout(() => { 74 | for (const entry of entries) { 75 | const event = new CustomEvent('bodyresize', { 76 | detail: entry 77 | }); 78 | entry.target.dispatchEvent(event); 79 | } 80 | }, 200); 81 | } 82 | })() 83 | 84 | window.resizeObserver = new ResizeObserver(onResizeCallback) 85 | window.resizeObserver.observe(document.body); 86 | } else { 87 | console.error("ResizeObserver not supported.") 88 | } 89 | fixBreadcrumbItems(); 90 | }) 91 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/renameVersionLinks.js: -------------------------------------------------------------------------------- 1 | function renameVersionLinks() { 2 | $('div.rst-other-versions dl:first-child a').each( function () { 3 | const text = $(this).text(); 4 | const versionRegEx = /^.*((?:[0-9]+\.){2}[0-9]+).*$/g; 5 | if (versionRegEx.test(text)) { 6 | $(this).text(text.replace(versionRegEx, '$1')); 7 | } 8 | }) 9 | } 10 | 11 | function waitForSelector(selector, callback, backoff=100, max=15) { 12 | let tries = 0; 13 | const waitInterval = setInterval(() => { 14 | if ($(selector).length > 0) { 15 | callback() 16 | clearInterval(waitInterval) 17 | } else { 18 | if (tries++ > max) { 19 | clearInterval(waitInterval) 20 | } 21 | } 22 | }, backoff) 23 | } 24 | 25 | $(document).ready(() => { 26 | waitForSelector('div.rst-versions', renameVersionLinks); 27 | }) 28 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/rocm_footer.css: -------------------------------------------------------------------------------- 1 | footer.rocm-footer { 2 | background-color: #000; 3 | color: #fff; 4 | padding: 1rem; 5 | z-index: 1999; 6 | padding-top: 0px; 7 | padding-bottom: 0px; 8 | } 9 | footer.rocm-footer a:not(.klavika-font) { 10 | color: #9d9fa2; 11 | font-size: 0.875rem; 12 | line-height: 1.25rem; 13 | margin-bottom: 0.625rem; 14 | text-decoration: none; 15 | } 16 | footer.rocm-footer a:not(.klavika-font):hover { 17 | color: #fff; 18 | text-decoration: underline; 19 | } 20 | footer.rocm-footer a.klavika-font:hover { 21 | text-decoration: underline; 22 | } 23 | @media (min-width: 768px) { 24 | footer.rocm-footer a.klavika-font { 25 | pointer-events: inherit; 26 | } 27 | } 28 | footer.rocm-footer section.menu ul { 29 | list-style: none; 30 | padding-left: 0; 31 | } 32 | footer.rocm-footer .bottom-menu ul > li { 33 | display: block; 34 | } 35 | footer.rocm-footer .bottom-menu ul > li a { 36 | font-size: 0.75rem; 37 | line-height: 1.125rem; 38 | } 39 | @media (min-width: 768px) { 40 | footer.rocm-footer .bottom-menu ul > li { 41 | display: inline-block; 42 | } 43 | footer.rocm-footer .bottom-menu ul > li:not(:last-child)::after { 44 | color: #9d9fa2; 45 | content: "|"; 46 | margin-left: 5px; 47 | } 48 | } 49 | footer.rocm-footer .bottom-menu .copyright { 50 | color: #9d9fa2; 51 | font-size: 0.75rem; 52 | line-height: 1.125rem; 53 | } 54 | 55 | @media (max-width: 959.98px) { 56 | input#__primary:checked ~ footer.rocm-footer { 57 | z-index: 1000; 58 | } 59 | } 60 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/search.js: -------------------------------------------------------------------------------- 1 | // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav. 2 | document.querySelector(".search-button-field.search-button__button").addEventListener("focusin", () => { 3 | const event = new CustomEvent("readthedocs-search-show"); 4 | document.dispatchEvent(event); 5 | }); 6 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/static/theme_mode_captions.js: -------------------------------------------------------------------------------- 1 | function modifyThemeModeCaptions() { 2 | var themeSwitchButtons = document.getElementsByClassName("theme-switch-button"); 3 | for (var i = 0; i < themeSwitchButtons.length; i++) { 4 | themeSwitchButtons[i].setAttribute("data-bs-original-title", document.documentElement.dataset.mode); 5 | } 6 | } 7 | 8 | function addModeListener() { 9 | const btn = document.getElementsByClassName("theme-switch-button")[0]; 10 | btn.addEventListener("click", modifyThemeModeCaptions); 11 | } 12 | 13 | $(addModeListener); 14 | $(window).ajaxComplete(function() { 15 | setTimeout(() => { 16 | modifyThemeModeCaptions(); 17 | }, 3000); 18 | }) 19 | -------------------------------------------------------------------------------- /src/rocm_docs/rocm_docs_theme/theme.conf: -------------------------------------------------------------------------------- 1 | [theme] 2 | inherit = sphinx_book_theme 3 | 4 | [options] 5 | body_max_width = none 6 | home_page_in_toc = False 7 | show_navbar_depth = 1 8 | show_toc_level = 1 9 | flavor = rocm 10 | 11 | link_main_doc = True 12 | 13 | # Generic theme options 14 | header_title = 15 | header_link = 16 | version_list_link = 17 | nav_secondary_items = 18 | license_link = 19 | license_text = 20 | -------------------------------------------------------------------------------- /src/rocm_docs/util.py: -------------------------------------------------------------------------------- 1 | """Utilities for rocm-docs-core.""" 2 | 3 | from __future__ import annotations 4 | 5 | from typing import Any 6 | 7 | import enum 8 | import functools 9 | import os 10 | import re 11 | from pathlib import Path 12 | 13 | import github 14 | from git.exc import InvalidGitRepositoryError 15 | from git.repo import Repo 16 | from github.GithubException import UnknownObjectException 17 | 18 | 19 | class VersionType(enum.Enum): 20 | """Describes how recent a version is (i.e. latest rc, or an older release)""" 21 | 22 | DEVELOPMENT = enum.auto() 23 | LATEST_RELEASE = enum.auto() 24 | OLD_RELEASE = enum.auto() 25 | RELEASE_CANDIDATE = enum.auto() 26 | 27 | 28 | def get_path_to_docs( 29 | conf_path: str | os.PathLike[Any] | None = None, 30 | repo_path: str | os.PathLike[Any] | None = None, 31 | ) -> str: 32 | """Get the relative path from the repo root to the docs.""" 33 | if conf_path is None: 34 | conf_path = Path() 35 | elif not isinstance(conf_path, Path): 36 | conf_path = Path(conf_path) 37 | if repo_path is None: 38 | repo_path = conf_path 39 | elif not isinstance(repo_path, Path): 40 | repo_path = Path(repo_path) 41 | repo = Repo(path=repo_path, search_parent_directories=True) 42 | return os.path.relpath(str(conf_path), repo.working_dir) 43 | 44 | 45 | @functools.lru_cache 46 | def get_branch( 47 | repo_path: str | os.PathLike[Any] | None = None, 48 | ) -> tuple[str, str]: 49 | """Get the branch whose tip is checked out, even if detached. 50 | 51 | May be overridden with the environment variable `ROCM_DOCS_REMOTE_DETAILS`. 52 | """ 53 | if "ROCM_DOCS_REMOTE_DETAILS" in os.environ: 54 | remote_details = os.environ["ROCM_DOCS_REMOTE_DETAILS"].split(",") 55 | return (remote_details[0], remote_details[1]) 56 | 57 | def get_repo_url(remote_url: str) -> str: 58 | ssh_pattern = re.compile(r"git@(\w+(?:\.\w+)+):(.*)\.git") 59 | http_pattern = re.compile(r"(https?://.+)\.git") 60 | remote_url, num_subs = ssh_pattern.subn( 61 | r"http://\1/\2", remote_url, count=1 62 | ) 63 | if num_subs > 0: 64 | return remote_url 65 | return http_pattern.sub(r"\1", remote_url, count=1) 66 | 67 | if os.environ.get("READTHEDOCS", ""): 68 | remote_url = os.environ.get("READTHEDOCS_GIT_CLONE_URL", "") 69 | url = get_repo_url(remote_url) 70 | build_type = os.environ["READTHEDOCS_VERSION_TYPE"] 71 | match = re.match(r"(?:.*://)?.*\.(com|io)[/:](.*)\.git", remote_url) 72 | assert match is not None 73 | repo_fqn: str = match[1] 74 | if build_type in ("branch", "tag"): 75 | return url, os.environ["READTHEDOCS_VERSION"] 76 | if build_type == "external": 77 | gh_inst = github.Github(os.environ.get("TOKEN", None)) 78 | print("Repository URL: " + repo_fqn) 79 | try: 80 | pull = gh_inst.get_repo(repo_fqn).get_pull( 81 | int(os.environ["READTHEDOCS_VERSION"]) 82 | ) 83 | return url, pull.head.ref 84 | except UnknownObjectException as err: 85 | if err.data["message"] == "Not Found": 86 | # Possibly a private repository that we're not 87 | # authenticated for, fallback 88 | return ( 89 | url, 90 | "external-" + os.environ["READTHEDOCS_VERSION"], 91 | ) 92 | # if build type is unknown try the usual strategy 93 | 94 | if repo_path is None: 95 | repo_path = Path() 96 | elif not isinstance(repo_path, Path): 97 | repo_path = Path(repo_path) 98 | repo = Repo(repo_path, search_parent_directories=True) 99 | assert not repo.bare 100 | for head in repo.heads: 101 | if head.commit == repo.head.commit: 102 | tracking = head.tracking_branch() 103 | if tracking is not None: 104 | remote_url = repo.remotes[tracking.remote_name].url 105 | remote_url = get_repo_url(remote_url) 106 | return remote_url, tracking.remote_head 107 | for remote in repo.remotes: 108 | for ref in remote.refs: 109 | if ref.commit == repo.head.commit: 110 | remote_url = get_repo_url(remote.url) 111 | return remote_url, ref.remote_head 112 | 113 | # Fall-back to the current branch or a fallback value if HEAD is detached 114 | # In this case the repository URL cannot be provided 115 | try: 116 | branch = repo.active_branch.name 117 | except TypeError: 118 | branch = "branch-not-found" 119 | 120 | return "", branch 121 | 122 | 123 | __all__ = [ 124 | "InvalidGitRepositoryError", 125 | "VersionType", 126 | "get_branch", 127 | "get_path_to_docs", 128 | ] 129 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- 1 | """Test utilities""" 2 | -------------------------------------------------------------------------------- /tests/conftest.py: -------------------------------------------------------------------------------- 1 | """Pytest Configuration""" 2 | 3 | from .log_fixtures import * 4 | from .projects_fixtures import * 5 | from .sphinx_fixtures import * 6 | 7 | pytest_plugins = ["sphinx.testing.fixtures"] 8 | -------------------------------------------------------------------------------- /tests/projects_fixtures.py: -------------------------------------------------------------------------------- 1 | """Defines fixtures for interacting with projects.py""" 2 | 3 | from __future__ import annotations 4 | 5 | from collections.abc import Callable 6 | 7 | import pytest 8 | 9 | import rocm_docs.projects 10 | 11 | 12 | @pytest.fixture 13 | def mock_projects( 14 | monkeypatch: pytest.MonkeyPatch, 15 | ) -> Callable[[dict[str, rocm_docs.projects._Project]], None]: 16 | """Mock the list of projects loaded by projects.py""" 17 | 18 | def do_mock(projects: dict[str, rocm_docs.projects._Project]) -> None: 19 | monkeypatch.setattr( 20 | "rocm_docs.projects._load_projects", 21 | lambda *_, **__: projects, 22 | ) 23 | 24 | return do_mock 25 | 26 | 27 | @pytest.fixture 28 | def mocked_projects( 29 | mock_projects: Callable[[dict[str, rocm_docs.projects._Project]], None], 30 | ) -> dict[str, rocm_docs.projects._Project]: 31 | """Standard mocked projects for tests""" 32 | projects = { 33 | "a": rocm_docs.projects._Project( 34 | "https://example.com/a", [], "", ".doxygen/docBin/html" 35 | ), 36 | "b": rocm_docs.projects._Project("https://example.com/b", [], ""), 37 | } 38 | mock_projects(projects) 39 | return projects 40 | -------------------------------------------------------------------------------- /tests/sites/doxygen/extension/conf.py: -------------------------------------------------------------------------------- 1 | extensions = ["rocm_docs", "rocm_docs.doxygen", "sphinxcontrib.doxylink"] 2 | html_theme = "rocm_docs_theme" 3 | 4 | external_projects_current_project = "a" 5 | 6 | doxygen_project = { 7 | "name": "ROCm Docs Core Test Project - Extension", 8 | "path": "doxygen/xml", 9 | } 10 | doxysphinx_enabled = True 11 | -------------------------------------------------------------------------------- /tests/sites/doxygen/legacy/conf.py: -------------------------------------------------------------------------------- 1 | from rocm_docs import ROCmDocs 2 | 3 | # base setup for using rocm-docs-core package 4 | docs_core = ROCmDocs("ROCm Docs Core Doxygen Test Project - Legacy") 5 | docs_core.setup() 6 | 7 | # doxygen integration 8 | docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") 9 | 10 | # doxysphinx integration 11 | docs_core.enable_api_reference() 12 | 13 | # used in intersphinx linking 14 | external_projects_current_project = "a" 15 | 16 | # custom path to table of contents 17 | external_toc_path = "./sphinx/_toc.yml" 18 | 19 | # set variables from rocm-docs-core for sphinx 20 | for sphinx_var in ROCmDocs.SPHINX_VARS: 21 | globals()[sphinx_var] = getattr(docs_core, sphinx_var) 22 | 23 | # optional extension for additional linking to doxygen 24 | if not "extensions" in globals(): 25 | extensions = [] 26 | extensions += ["sphinxcontrib.doxylink"] 27 | -------------------------------------------------------------------------------- /tests/sites/pass/minimal/conf.py: -------------------------------------------------------------------------------- 1 | extensions = ["rocm_docs"] 2 | html_theme = "rocm_docs_theme" 3 | 4 | external_projects_current_project = "a" 5 | -------------------------------------------------------------------------------- /tests/sites/pass/minimal_legacy/conf.py: -------------------------------------------------------------------------------- 1 | from rocm_docs import ROCmDocs 2 | 3 | docs_core = ROCmDocs("ROCm Docs Core Test Project - Minimal Legacy") 4 | docs_core.setup() 5 | 6 | for sphinx_var in ROCmDocs.SPHINX_VARS: 7 | globals()[sphinx_var] = getattr(docs_core, sphinx_var) 8 | 9 | external_projects_current_project = "a" 10 | -------------------------------------------------------------------------------- /tests/sites/templates/doxygen/.doxygen/A.cpp: -------------------------------------------------------------------------------- 1 | /** 2 | * \file 3 | * \author Jon Doe (jon@example.com) 4 | * \brief Test doxygen source 5 | * \version 0.1 6 | * \date 2023-03-23 7 | * \copyright Copyright (c) 2023 Advanced Micro Devices Inc. 8 | */ 9 | 10 | /** 11 | * \brief Root namespace of the example project 12 | * 13 | */ 14 | namespace my_project { 15 | 16 | /** 17 | * \defgroup a Group A 18 | * \brief The A group 19 | * @{ 20 | */ 21 | 22 | /** 23 | * \brief A struct 24 | */ 25 | struct MyStruct { 26 | 27 | /** 28 | * \brief A method 29 | */ 30 | void method(); 31 | }; 32 | 33 | /** 34 | * \brief A function inside the group 35 | */ 36 | void f(); 37 | 38 | /** 39 | * @} 40 | */ 41 | 42 | } // namespace my_project 43 | 44 | 45 | /** 46 | * \defgroup b Group B 47 | */ 48 | 49 | /** 50 | * \ingroup b 51 | * \brief A function 52 | */ 53 | void function_outside_group(); 54 | -------------------------------------------------------------------------------- /tests/sites/templates/doxygen/.sphinx/_toc.yml.in: -------------------------------------------------------------------------------- 1 | root: index.md 2 | entries: 3 | - file: a 4 | - file: breathe 5 | - file: doxylink 6 | - file: .doxygen/docBin/html/index 7 | title: Doxygen API Reference 8 | - title: External Project A 9 | url: ${project:a} 10 | - title: Externale Project B 11 | url: ${project:b} 12 | -------------------------------------------------------------------------------- /tests/sites/templates/doxygen/breathe.md: -------------------------------------------------------------------------------- 1 | # Test page for breathe 2 | 3 | ```{doxygengroup} a 4 | ``` 5 | 6 | ```{doxygengroup} b 7 | ``` 8 | -------------------------------------------------------------------------------- /tests/sites/templates/doxygen/doxylink.md: -------------------------------------------------------------------------------- 1 | # Test page for doxylink 2 | 3 | Test links to doxygen items: 4 | 5 | - File: {doxygen}`A.cpp` 6 | - Namespace: {doxygen}`my_project` 7 | - Class: {doxygen}`my_project::MyStruct` 8 | - Free function: {doxygen}`function_outside_group()` 9 | -------------------------------------------------------------------------------- /tests/sites/templates/minimal/.sphinx/_toc.yml.in: -------------------------------------------------------------------------------- 1 | root: index.md 2 | entries: 3 | - file: a.md 4 | - title: External Project A 5 | url: ${project:a} 6 | - title: External Project B 7 | url: ${project:b} 8 | -------------------------------------------------------------------------------- /tests/sites/templates/minimal/a.md: -------------------------------------------------------------------------------- 1 | # A subdocument 2 | -------------------------------------------------------------------------------- /tests/sites/templates/minimal/index.md: -------------------------------------------------------------------------------- 1 | # rocm-docs core test site 2 | -------------------------------------------------------------------------------- /tests/sites/templates/standard/a.md: -------------------------------------------------------------------------------- 1 | # A subdocument 2 | -------------------------------------------------------------------------------- /tests/sites/templates/standard/index.md: -------------------------------------------------------------------------------- 1 | # rocm-docs core test site 2 | -------------------------------------------------------------------------------- /tests/sites/templates/standard/sphinx/_toc.yml.in: -------------------------------------------------------------------------------- 1 | root: index.md 2 | entries: 3 | - file: a.md 4 | - title: External Project A 5 | url: ${project:a} 6 | - title: External Project B 7 | url: ${project:b} 8 | -------------------------------------------------------------------------------- /tests/sites/theme_flavors/rocm-blogs/conf.py: -------------------------------------------------------------------------------- 1 | extensions = ["rocm_docs"] 2 | html_theme = "rocm_docs_theme" 3 | html_theme_options = {"flavor": "rocm-blogs"} 4 | 5 | external_toc_path = "./sphinx/_toc.yml" 6 | 7 | external_projects_current_project = "a" 8 | 9 | version = "1.0.0" 10 | release = "1.0.0" 11 | html_title = f"ROCm Docs Core Theme Test Project - ROCm Blogs Flavor" 12 | project = "ROCm Docs Core" 13 | author = "Advanced Micro Devices, Inc." 14 | copyright = ( 15 | "Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved." 16 | ) 17 | -------------------------------------------------------------------------------- /tests/sites/theme_flavors/rocm-docs-home/conf.py: -------------------------------------------------------------------------------- 1 | extensions = ["rocm_docs"] 2 | html_theme = "rocm_docs_theme" 3 | html_theme_options = {"flavor": "rocm-docs-home"} 4 | 5 | external_toc_path = "./sphinx/_toc.yml" 6 | 7 | external_projects_current_project = "a" 8 | 9 | version = "1.0.0" 10 | release = "1.0.0" 11 | html_title = f"ROCm Docs Core Theme Test Project - ROCm Docs Home Flavor" 12 | project = "ROCm Docs Core" 13 | author = "Advanced Micro Devices, Inc." 14 | copyright = ( 15 | "Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved." 16 | ) 17 | -------------------------------------------------------------------------------- /tests/sites/theme_flavors/rocm/conf.py: -------------------------------------------------------------------------------- 1 | extensions = ["rocm_docs"] 2 | html_theme = "rocm_docs_theme" 3 | html_theme_options = {"flavor": "rocm"} 4 | 5 | external_toc_path = "./sphinx/_toc.yml" 6 | 7 | external_projects_current_project = "a" 8 | 9 | version = "1.0.0" 10 | release = "1.0.0" 11 | html_title = f"ROCm Docs Core Theme Test Project - ROCm Flavor" 12 | project = "ROCm Docs Core" 13 | author = "Advanced Micro Devices, Inc." 14 | copyright = ( 15 | "Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved." 16 | ) 17 | -------------------------------------------------------------------------------- /tests/sphinx_fixtures.py: -------------------------------------------------------------------------------- 1 | """Defines helpers for testing the rocm_docs sphinx extension""" 2 | 3 | from __future__ import annotations 4 | 5 | import functools 6 | import shutil 7 | from collections.abc import Callable, Iterator 8 | from pathlib import Path 9 | 10 | import pytest 11 | from sphinx.application import Sphinx 12 | 13 | from .log_fixtures import ExpectLogFixture 14 | 15 | 16 | @pytest.fixture 17 | def with_no_git_repo( 18 | monkeypatch: pytest.MonkeyPatch, 19 | expect_log: ExpectLogFixture, 20 | ) -> Iterator[ExpectLogFixture.Validator]: 21 | """Setup environment to allow testing outside a git repository""" 22 | monkeypatch.setenv("ROCM_DOCS_REMOTE_DETAILS", ",") 23 | 24 | with expect_log( 25 | "git.exc.InvalidGitRepositoryError", 26 | "ERROR", 27 | "test_external_projects", 28 | ) as validator: 29 | yield validator 30 | 31 | 32 | SITES_BASEFOLDER = Path(__file__).parent / "sites" 33 | 34 | 35 | def build_sphinx( 36 | srcdir: Path, outdir: Path, confdir: Path | None = None 37 | ) -> None: 38 | confdir = confdir or srcdir 39 | doctreedir = outdir / ".doctrees" 40 | buildername = "html" 41 | app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername) 42 | app.build() 43 | 44 | 45 | @pytest.fixture 46 | def build_factory( 47 | request: pytest.FixtureRequest, 48 | tmp_path: Path, 49 | ) -> Callable[..., tuple[Path, Path]]: 50 | """A factory to prepare Sphinx source and output directories""" 51 | 52 | def make(src_folder: Path, /) -> tuple[Path, Path]: 53 | srcdir = tmp_path.joinpath(src_folder) 54 | outdir = tmp_path.joinpath(f"{src_folder}_build") 55 | srcdir.parent.mkdir(parents=True, exist_ok=True) 56 | 57 | mark = request.node.get_closest_marker("template_folder") 58 | if mark is not None: 59 | for i, dir in enumerate(mark.args): 60 | shutil.copytree(dir, srcdir, dirs_exist_ok=(i > 0)) 61 | 62 | shutil.copytree( 63 | SITES_BASEFOLDER / src_folder, srcdir, dirs_exist_ok=True 64 | ) 65 | return srcdir, outdir 66 | 67 | if hasattr(request, "param"): 68 | return functools.partial(make, request.param) 69 | return make 70 | 71 | 72 | __all__ = ["build_factory", "with_no_git_repo"] 73 | -------------------------------------------------------------------------------- /tests/test_doxygen.py: -------------------------------------------------------------------------------- 1 | from __future__ import annotations 2 | 3 | from types import SimpleNamespace 4 | 5 | import copy 6 | import unittest.mock 7 | 8 | import pytest 9 | 10 | import rocm_docs.doxygen 11 | 12 | 13 | def test_copy_tagfile(tmp_path_factory: pytest.TempPathFactory) -> None: 14 | app = unittest.mock.NonCallableMock() 15 | 16 | srcdir = tmp_path_factory.mktemp("srcdir") 17 | srcfile = srcdir.joinpath("tagfile.xml") 18 | expected_content = "Dummy doxygen tagfile" 19 | srcfile.write_text(expected_content) 20 | 21 | outdir = tmp_path_factory.mktemp("outdir").absolute() 22 | outfile = outdir.joinpath("tagfile.xml") 23 | 24 | app.config.doxygen_html = "" 25 | app.builder = SimpleNamespace(format="html") 26 | app.outdir = str(outdir) 27 | app.srcdir = str(srcdir) 28 | 29 | rocm_docs.doxygen._copy_tagfile(app) 30 | 31 | assert outfile.read_text() == expected_content 32 | 33 | 34 | @pytest.mark.parametrize( 35 | ("output_format", "doxygen_html"), 36 | [("html", None), ("epub", "")], 37 | ids=["not_set", "skipped_format"], 38 | ) 39 | def test_copy_tagfile_skipped( 40 | tmp_path_factory: pytest.TempPathFactory, 41 | output_format: str, 42 | doxygen_html: str | None, 43 | ) -> None: 44 | app = unittest.mock.NonCallableMock() 45 | 46 | srcdir = tmp_path_factory.mktemp("srcdir") 47 | srcfile = srcdir.joinpath("tagfile.xml") 48 | srcfile.touch(exist_ok=False) 49 | 50 | outdir = tmp_path_factory.mktemp("outdir").absolute() 51 | outfile = outdir.joinpath("tagfile.xml") 52 | 53 | app.config.doxygen_html = doxygen_html 54 | app.builder = SimpleNamespace(format=output_format) 55 | app.outdir = str(outdir) 56 | app.srcdir = str(srcdir) 57 | 58 | rocm_docs.doxygen._copy_tagfile(app) 59 | 60 | assert not outfile.exists() 61 | 62 | 63 | @pytest.mark.parametrize( 64 | ("has_doxylink", "has_doxygen_html"), 65 | [(False, True), (True, False), (False, False)], 66 | ids=["no_doxylink", "no_html", "neither"], 67 | ) 68 | def test_update_doxylink_settings_skipped( 69 | has_doxylink: bool, has_doxygen_html: bool 70 | ) -> None: 71 | app = unittest.mock.NonCallableMock(spec=["config", "srcdir"]) 72 | app.srcdir = "" 73 | config_spec = ["doxygen_html", "overrides", "_raw_config"] 74 | 75 | if has_doxylink: 76 | config_spec.append("doxylink") 77 | 78 | config = unittest.mock.NonCallableMock(config_spec) 79 | config.doxygen_html = "doxygen/html" if has_doxygen_html else None 80 | config.overrides = [] 81 | config._raw_config = [] 82 | expected: dict[str, tuple[str, str]] 83 | if has_doxylink: 84 | expected = {"must-not-be-changed": ("tagfile.xml", "test-string")} 85 | config.doxylink = copy.copy(expected) 86 | app.config = config 87 | 88 | rocm_docs.doxygen._update_doxylink_settings(app, config) 89 | 90 | if has_doxylink: 91 | assert app.config.doxylink == expected 92 | else: 93 | assert not hasattr(app.config, "doxylink") 94 | -------------------------------------------------------------------------------- /tests/test_meta.py: -------------------------------------------------------------------------------- 1 | from __future__ import annotations 2 | 3 | import logging 4 | 5 | import pytest 6 | 7 | from .log_fixtures import ExpectLogFixture 8 | 9 | logger = logging.getLogger(__name__) 10 | 11 | 12 | def test_log_stack(expect_log: ExpectLogFixture) -> None: 13 | with expect_log(logger.name, "WARNING", "Foo"): 14 | logger.warning("Foo") 15 | with expect_log(logger.name, "WARNING", "Bar"): 16 | logger.warning("Bar") 17 | with expect_log(logger.name, "ERROR", "Baz"): 18 | logger.error("Baz") 19 | with expect_log(logger.name, "ERROR", "Qux"): 20 | logger.error("Qux") 21 | 22 | 23 | def test_scope_of_log_stack(expect_log: ExpectLogFixture) -> None: 24 | logger.info("Foo") 25 | with expect_log(logger.name, "INFO", "Foo", required=False) as res: 26 | pass 27 | logger.info("Foo") 28 | assert not res.found 29 | 30 | 31 | @pytest.mark.usefixtures("_no_unexpected_warnings") 32 | @pytest.mark.meta_invert_fixture 33 | def test_unexpected_warnings() -> None: 34 | logger.warning("An unexpected warning") 35 | 36 | 37 | @pytest.mark.usefixtures("_no_unexpected_warnings") 38 | def test_expected_warning( 39 | caplog: pytest.LogCaptureFixture, expected_logs: set[logging.LogRecord] 40 | ) -> None: 41 | logger.warning("An expected warning") 42 | records = caplog.get_records("call") 43 | assert len(records) == 1 44 | expected_logs.add(records[0]) 45 | -------------------------------------------------------------------------------- /tests/test_projects.py: -------------------------------------------------------------------------------- 1 | from __future__ import annotations 2 | 3 | from typing import Any, Literal 4 | 5 | import unittest.mock 6 | from pathlib import Path 7 | 8 | import pytest 9 | from sphinx.errors import ExtensionError 10 | 11 | import rocm_docs.projects 12 | 13 | from .log_fixtures import ExpectLogFixture 14 | from .sphinx_fixtures import SITES_BASEFOLDER 15 | 16 | TEMPLATE_FOLDER = SITES_BASEFOLDER / "templates" 17 | 18 | 19 | def str_or_list_to_id(val: str | list[str]) -> str: 20 | if isinstance(val, str): 21 | return val 22 | return ",".join(val) 23 | 24 | 25 | def create_app( 26 | srcdir: Path, external_projects: Any 27 | ) -> unittest.mock.NonCallableMock: 28 | app = unittest.mock.NonCallableMock() 29 | app.srcdir = srcdir 30 | app.config = unittest.mock.NonCallableMock() 31 | app.config.overrides = [] 32 | app.config._raw_config = { 33 | "external_projects_current_project": "a", 34 | "external_projects": external_projects, 35 | "external_toc_template_path": TEMPLATE_FOLDER 36 | / "minimal" 37 | / ".sphinx" 38 | / "_toc.yml.in", 39 | "external_toc_path": "_toc.yml", 40 | "intersphinx_mapping": {}, 41 | } 42 | app.config.configure_mock(**app.config._raw_config) 43 | return app 44 | 45 | 46 | @pytest.mark.parametrize( 47 | "external_projects", 48 | [[], ["a"], ["b"], ["a", "b"], "all"], 49 | ids=str_or_list_to_id, 50 | ) 51 | @pytest.mark.usefixtures("_no_unexpected_warnings") 52 | def test_external_projects( 53 | external_projects: list[str] | Literal["all"], 54 | mocked_projects: dict[str, rocm_docs.projects._Project], 55 | tmp_path: Path, 56 | with_no_git_repo: ExpectLogFixture.Validator, 57 | ) -> None: 58 | with_no_git_repo.required = False 59 | app = create_app(tmp_path, external_projects) 60 | rocm_docs.projects._update_config(app, app.config) 61 | 62 | keys = ( 63 | external_projects 64 | if external_projects != "all" 65 | else mocked_projects.keys() 66 | ) 67 | 68 | expected_mapping = { 69 | k: (v.target, tuple(v.inventory)) 70 | for k, v in mocked_projects.items() 71 | if k in keys 72 | } 73 | assert app.config.intersphinx_mapping == expected_mapping 74 | 75 | # Every project is available in the HTML templates and TOC, regardless of 76 | # the value of "external_projects" 77 | expected_context = {k: v.target for k, v in mocked_projects.items()} 78 | assert app.config.projects_context["projects"] == expected_context 79 | 80 | 81 | @pytest.mark.usefixtures("mocked_projects", "_no_unexpected_warnings") 82 | def test_external_projects_invalid_value( 83 | expect_log: ExpectLogFixture, 84 | with_no_git_repo: ExpectLogFixture.Validator, 85 | tmp_path: Path, 86 | ) -> None: 87 | with_no_git_repo.required = False 88 | app = create_app(tmp_path, "invalid_value") 89 | 90 | with expect_log( 91 | "sphinx.rocm_docs.projects", 92 | "ERROR", 93 | 'Unexpected value "invalid_value" in external_projects.\n' 94 | 'Must be set to a list of project names or "all" to enable all projects' 95 | " defined in projects.yaml", 96 | ): 97 | rocm_docs.projects._update_config(app, app.config) 98 | 99 | 100 | @pytest.mark.usefixtures("_no_unexpected_warnings") 101 | def test_external_projects_unknown_project( 102 | expect_log: ExpectLogFixture, 103 | mocked_projects: dict[str, rocm_docs.projects._Project], 104 | with_no_git_repo: ExpectLogFixture.Validator, 105 | tmp_path: Path, 106 | ) -> None: 107 | with_no_git_repo.required = False 108 | # First keys of mocked_projects 109 | a_defined_project = next(iter(mocked_projects.keys())) 110 | app = create_app(tmp_path, [a_defined_project, "unknown_project", "foo"]) 111 | 112 | with expect_log( 113 | "sphinx.rocm_docs.projects", 114 | "ERROR", 115 | 'Unknown projects: ["unknown_project", "foo"] in external_projects.\n' 116 | "Valid projects are: [{}]".format( 117 | ", ".join([f'"{p}"' for p in mocked_projects]) 118 | ), 119 | ): 120 | rocm_docs.projects._update_config(app, app.config) 121 | 122 | 123 | @pytest.mark.usefixtures("_no_unexpected_warnings") 124 | @pytest.mark.parametrize( 125 | "doxygen", ["doxygen/html", {"html": "doxygen/html"}], ids=["str", "dict"] 126 | ) 127 | def test_doxygen_html_types( 128 | doxygen: str | dict[str, str], 129 | ) -> None: 130 | result = rocm_docs.projects._Project._get_doxygen_html({"doxygen": doxygen}) # type: ignore 131 | assert result == "doxygen/html" 132 | 133 | 134 | @pytest.mark.usefixtures("_no_unexpected_warnings") 135 | @pytest.mark.parametrize( 136 | "doxygen_html", 137 | ["https:", "//has_netloc", "has#fragment", "has?query", "/absolute"], 138 | ) 139 | def test_doxygen_html_invalid( 140 | doxygen_html: str, 141 | ) -> None: 142 | with pytest.raises(ExtensionError): 143 | rocm_docs.projects._Project._get_doxygen_html({"doxygen": doxygen_html}) 144 | 145 | 146 | @pytest.mark.usefixtures("_no_unexpected_warnings") 147 | @pytest.mark.parametrize( 148 | "current_project", 149 | [None, rocm_docs.projects._Project("", [], "", None)], 150 | ids=["no_current_project", "not_set"], 151 | ) 152 | def test_set_doxygen_html_not_defined( 153 | current_project: rocm_docs.projects._Project | None, 154 | ) -> None: 155 | app = unittest.mock.NonCallableMock() 156 | app.config = unittest.mock.NonCallableMock() 157 | app.config.doxygen_html = "must-not-be-changed" 158 | rocm_docs.projects._set_doxygen_html(app, current_project) 159 | assert app.config.doxygen_html == "must-not-be-changed" 160 | 161 | 162 | @pytest.mark.usefixtures("_no_unexpected_warnings") 163 | def test_set_doxygen_html_mismatched(expect_log: ExpectLogFixture) -> None: 164 | app = create_app(Path(""), []) 165 | app.config.doxygen_html = "must-not-be-changed" 166 | app.config._raw_config["doxygen_html"] = "must-not-be-changed" 167 | with expect_log( 168 | "sphinx.rocm_docs.projects", 169 | "WARNING", 170 | 'The setting doxygen_html="must-not-be-changed"' 171 | ' differs from projects.yaml value: "does-not-match"', 172 | ): 173 | rocm_docs.projects._set_doxygen_html( 174 | app, rocm_docs.projects._Project("", [], "", "does-not-match") 175 | ) 176 | assert app.config.doxygen_html == "must-not-be-changed" 177 | --------------------------------------------------------------------------------