From ef39d5d5061c7c9120dad8fcc72a9be3f6126270 Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Tue, 31 Oct 2023 11:49:37 -0600 Subject: [PATCH] Standardize documentation (#201) * Standardize documentation Relates to https://github.com/RadeonOpenCompute/rocm-docs-core/issues/330 * Fix settings for doxygen integration and nav version Also ignore doc artifacts * Remove unnecessary and redundant documentation configurations --- .github/dependabot.yml | 2 +- .readthedocs.yaml | 4 ++-- README.md | 4 ++-- docs/.gitignore | 3 +++ docs/.sphinx/requirements.in | 1 - docs/conf.py | 23 ++++++++++++++++++++--- docs/{.doxygen => doxygen}/Doxyfile | 10 +++++----- docs/license.md | 4 ++++ docs/{.sphinx => sphinx}/_toc.yml.in | 3 +++ docs/sphinx/requirements.in | 1 + docs/{.sphinx => sphinx}/requirements.txt | 4 ++-- 11 files changed, 43 insertions(+), 16 deletions(-) create mode 100644 docs/.gitignore delete mode 100644 docs/.sphinx/requirements.in rename docs/{.doxygen => doxygen}/Doxyfile (99%) 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 (97%) 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/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..488f7c47 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +_doxygen/ +doxygen/html/ +doxygen/xml/ 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..5dcd622c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,14 +4,31 @@ # 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 \"?([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.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 99% rename from docs/.doxygen/Doxyfile rename to docs/doxygen/Doxyfile index 5bad0daa..7b12120a 100644 --- a/docs/.doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -51,7 +51,7 @@ PROJECT_BRIEF = "ROCm SOLVER marshalling library" # 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 @@ -1561,7 +1561,7 @@ MATHJAX_CODEFILE = # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -SEARCHENGINE = YES +SEARCHENGINE = NO # When the SERVER_BASED_SEARCH tag is enabled the search engine will be # implemented using a web server instead of a web client using Javascript. There @@ -2106,7 +2106,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 = +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 @@ -2337,7 +2337,7 @@ DIRECTORY_GRAPH = YES # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_IMAGE_FORMAT = png +DOT_IMAGE_FORMAT = svg # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to # enable generation of interactive SVG images that allow zooming and panning. @@ -2349,7 +2349,7 @@ DOT_IMAGE_FORMAT = png # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -INTERACTIVE_SVG = NO +INTERACTIVE_SVG = YES # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. 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..9b027ada --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core==0.26.0 diff --git a/docs/.sphinx/requirements.txt b/docs/sphinx/requirements.txt similarity index 97% rename from docs/.sphinx/requirements.txt rename to docs/sphinx/requirements.txt index b0b4766a..813eb260 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 @@ -92,7 +92,7 @@ requests==2.28.2 # via # pygithub # sphinx -rocm-docs-core>=0.20.0 +rocm-docs-core==0.26.0 # via -r requirements.in smmap==5.0.0 # via gitdb