diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9cdf2d670c..0e0a252eb6 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -6,7 +6,13 @@ version: 2 updates: - package-ecosystem: "pip" # See documentation for possible values - directory: "/docs/.sphinx" # Location of package manifests + directory: "/docs/sphinx" # Location of package manifests open-pull-requests-limit: 10 schedule: interval: "daily" + labels: + - "documentation" + - "dependencies" + - "ci:docs-only" + reviewers: + - "samjwu" diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1240c9c525..2439bb85c9 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,14 +6,14 @@ version: 2 sphinx: configuration: docs/conf.py -formats: [htmlzip] +formats: [htmlzip, pdf, epub] python: install: - - requirements: docs/.sphinx/requirements.txt + - requirements: docs/sphinx/requirements.txt build: - os: ubuntu-20.04 + os: ubuntu-22.04 tools: python: "3.8" apt_packages: diff --git a/docs/.gitignore b/docs/.gitignore index 8f68c925a3..53b7787fbd 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,4 +2,7 @@ /_doxygen /_images /_static -/_templates \ No newline at end of file +/_templates +/doxygen/html +/doxygen/xml +/sphinx/_toc.yml diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in deleted file mode 100644 index 67a925b2c9..0000000000 --- a/docs/.sphinx/requirements.in +++ /dev/null @@ -1 +0,0 @@ -rocm-docs-core[api_reference]==0.11.0 diff --git a/docs/conf.py b/docs/conf.py index 62b6736eba..251b58acd0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,23 +4,36 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -from rocm_docs import ROCmDocs +import re from typing import Any, Dict, List -docs_core = ROCmDocs("HIP Documentation") -docs_core.run_doxygen() +from rocm_docs import ROCmDocs + +version_numbers = [] +version_file = open("../VERSION", "r") +lines = version_file.readlines() +for line in lines: + if line[0] == '#': + continue + version_numbers.append(line.strip()) +version_number = ".".join(version_numbers) +left_nav_title = f"HIP {version_number} Documentation" + +# for PDF output on Read the Docs +project = "HIP Documentation" +author = "Advanced Micro Devices, Inc." +copyright = "Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved." +version = version_number +release = version_number + +external_toc_path = "./sphinx/_toc.yml" + +docs_core = ROCmDocs(left_nav_title) +docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") docs_core.enable_api_reference() docs_core.setup() +external_projects_current_project = "hip" + for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) - -# rocm-docs-core might or might not have changed these yet (depending on version), -# and we don't want to wipe their settings if they did -if not "html_theme_options" in globals(): - html_theme_options: Dict[str, Any] = {} -if not "exclude_patterns" in globals(): - exclude_patterns: List[str] = [] - -html_theme_options["show_navbar_depth"] = 2 -exclude_patterns.append(".doxygen/mainpage.md") diff --git a/docs/.doxygen/Doxyfile b/docs/doxygen/Doxyfile similarity index 99% rename from docs/.doxygen/Doxyfile rename to docs/doxygen/Doxyfile index b4eb6a1a5f..6784e0da92 100644 --- a/docs/.doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docBin +OUTPUT_DIRECTORY = . # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -2237,7 +2237,7 @@ TAGFILES = # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = docBin/html/tagfile.xml +GENERATE_TAGFILE = html/tagfile.xml # If the ALLEXTERNALS tag is set to YES, all external class will be listed in # the class index. If set to NO, only the inherited external classes will be diff --git a/docs/.doxygen/mainpage.md b/docs/doxygen/mainpage.md similarity index 100% rename from docs/.doxygen/mainpage.md rename to docs/doxygen/mainpage.md diff --git a/docs/index.md b/docs/index.md index a2a7c89f20..bcc9d7fdb9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,8 +20,8 @@ portable applications for AMD and NVIDIA GPUs from single source code. ::: :::{grid-item-card} Reference -- {doc}`/.doxygen/docBin/html/index` - - {doc}`/.doxygen/docBin/html/modules` +- {doc}`/doxygen/html/index` + - {doc}`/doxygen/html/modules` - {doc}`/reference/kernel_language` - {doc}`/reference/math_api` - {doc}`/reference/terms` @@ -34,4 +34,4 @@ portable applications for AMD and NVIDIA GPUs from single source code. - {doc}`/developer_guide/contributing` ::: -:::: \ No newline at end of file +:::: diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000000..27dad28c7a --- /dev/null +++ b/docs/license.md @@ -0,0 +1,4 @@ +# License + +```{include} ../LICENSE.txt +``` diff --git a/docs/.sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in similarity index 84% rename from docs/.sphinx/_toc.yml.in rename to docs/sphinx/_toc.yml.in index dc07d17d8a..fc06dd0b8b 100644 --- a/docs/.sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -13,7 +13,7 @@ subtrees: - file: how_to_guides/debugging.md - caption: Reference entries: - - file: .doxygen/docBin/html/index + - file: doxygen/html/index - file: reference/kernel_language - file: reference/math_api - file: reference/terms @@ -23,4 +23,7 @@ subtrees: entries: - file: developer_guide/build - file: developer_guide/logging - - file: developer_guide/contributing.md \ No newline at end of file + - file: developer_guide/contributing.md +- caption: About + entries: + - file: license diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 0000000000..1bebff82f9 --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core[api_reference]==0.26.0 diff --git a/docs/.sphinx/requirements.txt b/docs/sphinx/requirements.txt similarity index 87% rename from docs/.sphinx/requirements.txt rename to docs/sphinx/requirements.txt index a52f70a92d..991fdec2e4 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.8 +# This file is autogenerated by pip-compile with Python 3.10 # by the following command: # # pip-compile requirements.in @@ -41,7 +41,7 @@ docutils==0.16 # myst-parser # pydata-sphinx-theme # sphinx -doxysphinx==3.2.1 +doxysphinx==3.3.7 # via rocm-docs-core fastjsonschema==2.16.2 # via rocm-docs-core @@ -53,18 +53,12 @@ idna==3.3 # via requests imagesize==1.4.1 # via sphinx -importlib-metadata==5.1.0 - # via sphinx -importlib-resources==5.10.4 - # via rocm-docs-core jinja2==3.1.2 # via # myst-parser # sphinx -json5==0.9.11 +libsass==0.22.0 # via doxysphinx -linkify-it-py==1.0.3 - # via myst-parser lxml==4.9.2 # via doxysphinx markdown-it-py==2.1.0 @@ -77,7 +71,9 @@ mdit-py-plugins==0.3.5 # via myst-parser mdurl==0.1.2 # via markdown-it-py -myst-parser[linkify]==1.0.0 +mpire==2.8.0 + # via doxysphinx +myst-parser==1.0.0 # via rocm-docs-core packaging==21.3 # via @@ -94,8 +90,11 @@ pygithub==1.58.2 pygments==2.12.0 # via # accessible-pygments + # mpire # pydata-sphinx-theme # sphinx +pyjson5==1.6.4 + # via doxysphinx pyjwt[crypto]==2.6.0 # via pygithub pynacl==1.5.0 @@ -115,7 +114,7 @@ requests==2.28.1 # via # pygithub # sphinx -rocm-docs-core[api_reference]==0.11.0 +rocm-docs-core[api_reference]==0.26.0 # via -r requirements.in smmap==5.0.0 # via gitdb @@ -156,15 +155,11 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx +tqdm==4.66.1 + # via mpire typing-extensions==4.4.0 # via pydata-sphinx-theme -uc-micro-py==1.0.1 - # via linkify-it-py urllib3==1.26.11 # via requests wrapt==1.15.0 # via deprecated -zipp==3.11.0 - # via - # importlib-metadata - # importlib-resources