Skip to content

Commit

Permalink
Apply and standardize Read the Docs documentation for HIPCC
Browse files Browse the repository at this point in the history
Relates to #12

Relates to ROCm/rocm-docs-core#330

Change-Id: Ic6a67f6edb21898c2ac8cf1dce91e94c507af4ad
  • Loading branch information
samjwu committed Nov 8, 2023
1 parent 427e3b3 commit 65d0571
Show file tree
Hide file tree
Showing 9 changed files with 52 additions and 14 deletions.
11 changes: 11 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
version: 2
updates:
- package-ecosystem: "pip" # See documentation for possible values
directory: "/amd/hipcc/docs/sphinx" # Location of package manifests
open-pull-requests-limit: 10
schedule:
interval: "daily"
labels:
- "documentation"
reviewers:
- "samjwu"
4 changes: 2 additions & 2 deletions amd/hipcc/.readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ 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"
18 changes: 10 additions & 8 deletions amd/hipcc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,39 +5,41 @@
<!-- toc -->

- [hipcc](#hipcc)
* [Documentation](#documentation)
* [Environment Variables](#envVar)
* [Usage](#hipcc-usage)
* [Building](#building)
* [Testing](#testing)
- [Documentation](#documentation)
- [Environment Variables](#envVar)
- [Usage](#usage)
- [Building](#building)
- [Testing](#testing)

<!-- tocstop -->

## <a name="hipcc"></a> hipcc

`hipcc` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. Historically, `hipcc` was provided as a script in the HIP repo ( https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc ). The `hipcc` provided in this project provides the same functionality, but is a binary rather than a script. At some point in the future, the hipcc script will be deprecated and ultimately removed from the HIP repo.
`hipcc` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. Historically, `hipcc` was provided as a script in the HIP repo [https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc](https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc). The `hipcc` provided in this project provides the same functionality, but is a binary rather than a script. At some point in the future, the hipcc script will be deprecated and ultimately removed from the HIP repo.

`hipcc` will pass-through options to the target compiler. The tools calling hipcc must ensure the compiler options are appropriate for the target compiler.

## Documentation

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
```

### <a name="envVar"></a> Environment Variables

The environment variable HIP_PLATFORM may be used to specify amd/nvidia:

- HIP_PLATFORM='amd' or HIP_PLATFORM='nvidia'.
- If HIP_PLATFORM is not set, then hipcc will attempt to auto-detect based on if nvcc is found.

Other environment variable controls:

- HIP_PATH : Path to HIP directory, default is one dir level above location of hipcc.
- CUDA_PATH : Path to CUDA SDK (default /usr/local/cuda). Used on NVIDIA platforms only.
- HSA_PATH : Path to HSA dir (defaults to ../../hsa relative to abs_path of hipcc). Used on AMD platforms only.
Expand Down
1 change: 0 additions & 1 deletion amd/hipcc/docs/.sphinx/requirements.in

This file was deleted.

20 changes: 19 additions & 1 deletion amd/hipcc/docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,27 @@
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import re

from rocm_docs import ROCmDocs

docs_core = ROCmDocs("HIPCC Documentation")
with open('../CMakeLists.txt', encoding='utf-8') as f:
match = re.search(r'.*\bproject\(hipcc VERSION\s+\"?([0-9.]+)[^0-9.]+', f.read())
if not match:
raise ValueError("VERSION not found!")
version_number = match[1]
left_nav_title = f"HIPCC {version_number} Documentation"

# for PDF output on Read the Docs
project = "HIPCC 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.setup()

for sphinx_var in ROCmDocs.SPHINX_VARS:
Expand Down
4 changes: 4 additions & 0 deletions amd/hipcc/docs/license.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# License

```{include} ../LICENSE.txt
```
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,6 @@ subtrees:
- file: usage
- file: build
- file: test
- caption: About
entries:
- file: license
1 change: 1 addition & 0 deletions amd/hipcc/docs/sphinx/requirements.in
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
rocm-docs-core==0.27.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.24.0
rocm-docs-core==0.27.0
# via -r requirements.in
smmap==5.0.0
# via gitdb
Expand Down

0 comments on commit 65d0571

Please sign in to comment.