Skip to content

Commit

Permalink
Standardize documentation (#201)
Browse files Browse the repository at this point in the history
* Standardize documentation

Relates to ROCm/rocm-docs-core#330

* Fix settings for doxygen integration and nav version

Also ignore doc artifacts

* Remove unnecessary and redundant documentation configurations
  • Loading branch information
samjwu authored Oct 31, 2023
1 parent 10ff267 commit ef39d5d
Show file tree
Hide file tree
Showing 11 changed files with 43 additions and 16 deletions.
2 changes: 1 addition & 1 deletion .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down
3 changes: 3 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
_doxygen/
doxygen/html/
doxygen/xml/
1 change: 0 additions & 1 deletion docs/.sphinx/requirements.in

This file was deleted.

23 changes: 20 additions & 3 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
10 changes: 5 additions & 5 deletions docs/.doxygen/Doxyfile → docs/doxygen/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions docs/license.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# License

```{include} ../LICENSE.md
```
3 changes: 3 additions & 0 deletions docs/.sphinx/_toc.yml.in → docs/sphinx/_toc.yml.in
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,6 @@ subtrees:
- file: refactor-api/types
- file: refactor-api/helpers
- file: refactor-api/refactor
- caption: About
entries:
- file: license
1 change: 1 addition & 0 deletions docs/sphinx/requirements.in
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
rocm-docs-core==0.26.0
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit ef39d5d

Please sign in to comment.