From 3cbf01f51eb8a64ba5f5c0733a7e8cac6bcb0846 Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Mon, 15 Jan 2024 11:24:36 -0700 Subject: [PATCH] Standardize documentation for ReadtheDocs (#97) --- .github/dependabot.yml | 8 +++++- .readthedocs.yaml | 6 ++--- README.md | 2 +- docs/.gitignore | 7 ++--- docs/.sphinx/requirements.in | 2 -- docs/conf.py | 26 ++++++++++++++++--- docs/{.doxygen => doxygen}/Doxyfile | 2 +- docs/{.doxygen => doxygen}/hipranddevice.dox | 0 docs/{.doxygen => doxygen}/hiprandhost.dox | 0 docs/{.doxygen => doxygen}/hiprandhostcpp.dox | 0 docs/{.doxygen => doxygen}/mainpage.dox | 0 docs/license.rst | 4 +++ docs/{.sphinx => sphinx}/_toc.yml.in | 3 +++ docs/sphinx/requirements.in | 2 ++ docs/{.sphinx => sphinx}/requirements.txt | 12 ++++++++- 15 files changed, 59 insertions(+), 15 deletions(-) delete mode 100644 docs/.sphinx/requirements.in rename docs/{.doxygen => doxygen}/Doxyfile (99%) rename docs/{.doxygen => doxygen}/hipranddevice.dox (100%) rename docs/{.doxygen => doxygen}/hiprandhost.dox (100%) rename docs/{.doxygen => doxygen}/hiprandhostcpp.dox (100%) rename docs/{.doxygen => doxygen}/mainpage.dox (100%) create mode 100644 docs/license.rst rename docs/{.sphinx => sphinx}/_toc.yml.in (81%) create mode 100644 docs/sphinx/requirements.in rename docs/{.sphinx => sphinx}/requirements.txt (92%) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9cdf2d6..0e0a252 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 2c1c206..9e6678a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,13 +6,13 @@ 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" diff --git a/README.md b/README.md index 10fc890..318f26e 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ To build our documentation, use the following commands: cd hipRAND; cd docs # Install Python dependencies -python3 -m pip install -r .sphinx/requirements.txt +python3 -m pip install -r sphinx/requirements.txt # Build the documentation python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html diff --git a/docs/.gitignore b/docs/.gitignore index bb5ec98..d9fe2f7 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,6 @@ /_build/ /_doxygen/ -/.doxygen/docBin/ -/.doxygen/*.tag -/.sphinx/_toc.yml +/doxygen/html/ +/doxygen/xml/ +/doxygen/*.tag +/sphinx/_toc.yml diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in deleted file mode 100644 index 416f0db..0000000 --- a/docs/.sphinx/requirements.in +++ /dev/null @@ -1,2 +0,0 @@ -rocm-docs-core>=0.24.0 -numpy diff --git a/docs/conf.py b/docs/conf.py index 356d927..62f625b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,19 +4,39 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -from rocm_docs import ROCmDocs import pathlib +import re import sys +from rocm_docs import ROCmDocs + # We need to add the location of the hiprand Python module to the PATH # in order to build the documentation of that module docs_dir_path = pathlib.Path(__file__).parent python_dir_path = docs_dir_path.parent / 'python' / 'hiprand' sys.path.append(str(python_dir_path)) -docs_core = ROCmDocs("hipRAND Documentation") -docs_core.run_doxygen() +with open('../CMakeLists.txt', encoding='utf-8') as f: + match = re.search(r'.*\bset\(hipRAND_VERSION\s+\"?([0-9.]+)[^0-9.]+', f.read()) + if not match: + raise ValueError("VERSION not found!") + version_number = match[1] +left_nav_title = f"hipRAND {version_number} Documentation" + +# for PDF output on Read the Docs +project = "hipRAND Documentation" +author = "Advanced Micro Devices, Inc." +copyright = "Copyright (c) 2024 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.setup() +external_projects_current_project = "hiprand" + for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) diff --git a/docs/.doxygen/Doxyfile b/docs/doxygen/Doxyfile similarity index 99% rename from docs/.doxygen/Doxyfile rename to docs/doxygen/Doxyfile index ddadc3a..bdfe7ed 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 diff --git a/docs/.doxygen/hipranddevice.dox b/docs/doxygen/hipranddevice.dox similarity index 100% rename from docs/.doxygen/hipranddevice.dox rename to docs/doxygen/hipranddevice.dox diff --git a/docs/.doxygen/hiprandhost.dox b/docs/doxygen/hiprandhost.dox similarity index 100% rename from docs/.doxygen/hiprandhost.dox rename to docs/doxygen/hiprandhost.dox diff --git a/docs/.doxygen/hiprandhostcpp.dox b/docs/doxygen/hiprandhostcpp.dox similarity index 100% rename from docs/.doxygen/hiprandhostcpp.dox rename to docs/doxygen/hiprandhostcpp.dox diff --git a/docs/.doxygen/mainpage.dox b/docs/doxygen/mainpage.dox similarity index 100% rename from docs/.doxygen/mainpage.dox rename to docs/doxygen/mainpage.dox diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..60fbe85 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,4 @@ +License +======= + +.. include:: ../LICENSE.txt diff --git a/docs/.sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in similarity index 81% rename from docs/.sphinx/_toc.yml.in rename to docs/sphinx/_toc.yml.in index 49f9b05..b4705cb 100644 --- a/docs/.sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -6,3 +6,6 @@ subtrees: - file: installing - file: cpp_api - file: python_api +- caption: About + entries: + - file: license diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 0000000..e038133 --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1,2 @@ +rocm-docs-core==0.30.3 +numpy diff --git a/docs/.sphinx/requirements.txt b/docs/sphinx/requirements.txt similarity index 92% rename from docs/.sphinx/requirements.txt rename to docs/sphinx/requirements.txt index 59f47e4..f60a5fd 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -46,6 +46,10 @@ idna==3.4 # via requests imagesize==1.4.1 # via sphinx +importlib-metadata==7.0.1 + # via sphinx +importlib-resources==6.1.1 + # via rocm-docs-core jinja2==3.1.2 # via # myst-parser @@ -85,6 +89,8 @@ pyjwt[crypto]==2.6.0 # via pygithub pynacl==1.5.0 # via pygithub +pytz==2023.3.post1 + # via babel pyyaml==6.0 # via # myst-parser @@ -94,7 +100,7 @@ requests==2.28.2 # via # pygithub # sphinx -rocm-docs-core>=0.24.0 +rocm-docs-core==0.30.3 # via -r requirements.in smmap==5.0.0 # via gitdb @@ -141,3 +147,7 @@ urllib3==1.26.15 # via requests wrapt==1.15.0 # via deprecated +zipp==3.17.0 + # via + # importlib-metadata + # importlib-resources