From 13a2bdd82533c4908052c076e29ba4dfcc761630 Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Wed, 25 Oct 2023 16:11:39 -0600 Subject: [PATCH] Standardize documentation Relates to https://github.com/RadeonOpenCompute/rocm-docs-core/issues/330 --- .github/dependabot.yml | 2 +- .readthedocs.yaml | 4 ++-- README.md | 4 ++-- docs/.sphinx/requirements.in | 1 - docs/conf.py | 25 +++++++++++++++++++--- docs/{.doxygen => doxygen}/Doxyfile | 0 docs/license.md | 4 ++++ docs/{.sphinx => sphinx}/_toc.yml.in | 3 +++ docs/sphinx/requirements.in | 1 + docs/{.sphinx => sphinx}/requirements.txt | 26 ++++++++++++++++++++--- 10 files changed, 58 insertions(+), 12 deletions(-) delete mode 100644 docs/.sphinx/requirements.in rename docs/{.doxygen => doxygen}/Doxyfile (100%) create mode 100644 docs/license.md rename docs/{.sphinx => sphinx}/_toc.yml.in (94%) create mode 100644 docs/sphinx/requirements.in rename docs/{.sphinx => sphinx}/requirements.txt (85%) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 5574dc0b..48ba3e0d 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -6,7 +6,7 @@ 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" diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9c33bf3c..9e6678ab 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,11 +6,11 @@ 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-22.04 diff --git a/README.md b/README.md index 3e2803fb..98ee0d54 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,10 @@ For a detailed description of the hipSOLVER library, its implemented routines, t Run the steps below to build documentation locally. -``` +```shell cd docs -pip3 install -r .sphinx/requirements.txt +pip3 install -r sphinx/requirements.txt python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html ``` diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in deleted file mode 100644 index 781cd3ac..00000000 --- a/docs/.sphinx/requirements.in +++ /dev/null @@ -1 +0,0 @@ -rocm-docs-core>=0.20.0 diff --git a/docs/conf.py b/docs/conf.py index 75144ca0..226e535e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,14 +4,33 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import re + from rocm_docs import ROCmDocs +with open('../CMakeLists.txt', encoding='utf-8') as f: + match = re.search(r'set \(VERSION_STRING\s+\"?([0-9.]+)[^0-9.]+', f.read()) + if not match: + raise ValueError("VERSION not found!") + version_number = match[1] +left_nav_title = f"hipSOLVER {version_number} Documentation" -external_projects_current_project = "hipsolver" +# for PDF output on Read the Docs +project = "hipSOLVER 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("hipSOLVER Documentation") -docs_core.run_doxygen() +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() +docs_core.setup() + +external_projects_current_project = "hipsolver" 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 100% rename from docs/.doxygen/Doxyfile rename to docs/doxygen/Doxyfile diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..b6e36d77 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,4 @@ +# License + +```{include} ../LICENSE.md +``` diff --git a/docs/.sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in similarity index 94% rename from docs/.sphinx/_toc.yml.in rename to docs/sphinx/_toc.yml.in index d2c4c50e..e46079ef 100644 --- a/docs/.sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -32,3 +32,6 @@ subtrees: - file: refactor-api/types - file: refactor-api/helpers - file: refactor-api/refactor + - caption: About + entries: + - file: license diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 00000000..1bebff82 --- /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 85% rename from docs/.sphinx/requirements.txt rename to docs/sphinx/requirements.txt index b0b4766a..4f839e61 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 @@ -25,7 +25,12 @@ cffi==1.15.1 charset-normalizer==3.1.0 # via requests click==8.1.3 - # via sphinx-external-toc + # via + # click-log + # doxysphinx + # sphinx-external-toc +click-log==0.4.0 + # via doxysphinx cryptography==40.0.2 # via pyjwt deprecated==1.2.13 @@ -36,6 +41,8 @@ docutils==0.19 # myst-parser # pydata-sphinx-theme # sphinx +doxysphinx==3.3.7 + # via rocm-docs-core fastjsonschema==2.16.3 # via rocm-docs-core gitdb==4.0.10 @@ -50,6 +57,10 @@ jinja2==3.1.2 # via # myst-parser # sphinx +libsass==0.22.0 + # via doxysphinx +lxml==4.9.3 + # via doxysphinx markdown-it-py==2.2.0 # via # mdit-py-plugins @@ -60,6 +71,8 @@ mdit-py-plugins==0.3.5 # via myst-parser mdurl==0.1.2 # via markdown-it-py +mpire==2.8.0 + # via doxysphinx myst-parser==1.0.0 # via rocm-docs-core packaging==23.0 @@ -77,12 +90,17 @@ pygithub==1.58.1 pygments==2.14.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 # via pygithub +pyparsing==3.1.1 + # via doxysphinx pyyaml==6.0 # via # myst-parser @@ -92,7 +110,7 @@ requests==2.28.2 # via # pygithub # sphinx -rocm-docs-core>=0.20.0 +rocm-docs-core[api_reference]==0.26.0 # via -r requirements.in smmap==5.0.0 # via gitdb @@ -133,6 +151,8 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx +tqdm==4.66.1 + # via mpire typing-extensions==4.5.0 # via pydata-sphinx-theme urllib3==1.26.15