From 11612c3a19df56d19d0214e8ccd74a37ec6ff19f Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Wed, 25 Oct 2023 16:52:56 -0600 Subject: [PATCH] Documentation standardization Relates to https://github.com/RadeonOpenCompute/rocm-docs-core/issues/330 --- .github/dependabot.yml | 8 +++++++- .readthedocs.yaml | 2 +- README.md | 2 +- docs/.gitignore | 3 +++ docs/.sphinx/requirements.in | 1 - docs/conf.py | 24 +++++++++++++++++++++-- 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, 49 insertions(+), 13 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 9cdf2d670..0e0a252eb 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 4192a0418..9e6678abe 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,7 +10,7 @@ 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 0b65ac56a..82c27c602 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Please follow the instructions below to build the documentation. ``` 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 000000000..488f7c478 --- /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 e505b2819..000000000 --- a/docs/.sphinx/requirements.in +++ /dev/null @@ -1 +0,0 @@ -rocm-docs-core==0.24.2 diff --git a/docs/conf.py b/docs/conf.py index 21d3f431b..d26d4bb9c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,11 +4,31 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import re + from rocm_docs import ROCmDocs -docs_core = ROCmDocs("rocSOLVER Documentation") -docs_core.run_doxygen() +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"rocSOLVER {version_number} Documentation" + +# for PDF output on Read the Docs +project = "rocSOLVER 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.setup() +external_projects_current_project = "rocsolver" + 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 3f99595a5..588101917 100644 --- a/docs/.doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -57,7 +57,7 @@ PROJECT_BRIEF = "implementation of LAPACK routines on the ROCm platform # 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 @@ -1575,7 +1575,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 @@ -2123,7 +2123,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 @@ -2354,7 +2354,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. @@ -2366,7 +2366,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 000000000..b6e36d773 --- /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 e85c38575..2ea071167 100644 --- a/docs/.sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -30,3 +30,6 @@ subtrees: - file: api/refact - file: api/logging - file: api/deprecated + - caption: About + entries: + - file: license diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 000000000..9b027ada3 --- /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 83cf58215..df26966b5 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.31.0 # via # pygithub # sphinx -rocm-docs-core==0.24.2 +rocm-docs-core==0.26.0 # via -r requirements.in smmap==5.0.0 # via gitdb