mirror of
https://github.com/ROCm/ROCm.git
synced 2026-01-09 14:48:06 -05:00
Update Toolchain and Contributing Guides (#2315)
* spell out HPC acronym in explanation doc * update toolchain docs order in importance descending * update Contributing guide add discussions update formatting and grammar * separate contributing section for readability * fix formatting for mdl * fix spelling
This commit is contained in:
Sam Wu
@@ -1,5 +1,11 @@
|
||||
# isv_deployment_win
|
||||
ABI
|
||||
# building
|
||||
matchers
|
||||
# file_reorg
|
||||
FHS
|
||||
incrementing
|
||||
Filesystem
|
||||
filesystem
|
||||
rocm
|
||||
# gpu_aware_mpi
|
||||
DMA
|
||||
GDR
|
||||
@@ -15,6 +21,8 @@ PeerDirect
|
||||
RDMA
|
||||
UCX
|
||||
ib_core
|
||||
# isv_deployment_win
|
||||
ABI
|
||||
# linear algebra
|
||||
LAPACK
|
||||
MMA
|
||||
@@ -95,9 +103,3 @@ DGEMM
|
||||
HPCG
|
||||
HPL
|
||||
IOPM
|
||||
# file_reorg
|
||||
FHS
|
||||
incrementing
|
||||
Filesystem
|
||||
filesystem
|
||||
rocm
|
||||
|
||||
230
CONTRIBUTING.md
230
CONTRIBUTING.md
@@ -2,7 +2,7 @@
|
||||
|
||||
AMD values and encourages the ROCm community to contribute to our code and
|
||||
documentation. This repository is focused on ROCm documentation and this
|
||||
contribution guide describes the recommend method for creating and modifying our
|
||||
contribution guide describes the recommended method for creating and modifying our
|
||||
documentation.
|
||||
|
||||
While interacting with ROCm Documentation, we encourage you to be polite and
|
||||
@@ -15,57 +15,38 @@ GitHub repository.
|
||||
|
||||
## Supported Formats
|
||||
|
||||
Our documentation includes both markdown and rst files. Markdown is encouraged
|
||||
over rst due to the lower barrier to participation. GitHub flavored markdown is preferred
|
||||
for all submissions as it will render accurately on our GitHub repositories. For existing documentation,
|
||||
[MyST](https://myst-parser.readthedocs.io/en/latest/intro.html) markdown
|
||||
is used to implement certain features unsupported in GitHub markdown. This is
|
||||
Our documentation includes both Markdown and RST files. Markdown is encouraged
|
||||
over RST due to the lower barrier to participation. GitHub flavored Markdown is preferred
|
||||
for all submissions as it renders accurately on our GitHub repositories. For existing documentation,
|
||||
[MyST](https://myst-parser.readthedocs.io/en/latest/intro.html) Markdown
|
||||
is used to implement certain features unsupported in GitHub Markdown. This is
|
||||
not encouraged for new documentation. AMD will transition
|
||||
to stricter use of GitHub flavored markdown with a few caveats. ROCm documentation
|
||||
also uses [sphinx-design](https://sphinx-design.readthedocs.io/en/latest/index.html)
|
||||
in our markdown and rst files. We also will use breathe syntax for doxygen documentation
|
||||
in our markdown files. Other design elements for effective HTML rendering of the documents
|
||||
may be added to our markdown files. Please see
|
||||
to stricter use of GitHub flavored Markdown with a few caveats. ROCm documentation
|
||||
also uses [Sphinx Design](https://sphinx-design.readthedocs.io/en/latest/index.html)
|
||||
in our Markdown and RST files. We also use Breathe syntax for Doxygen documentation
|
||||
in our Markdown files. See
|
||||
[GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github)'s
|
||||
guide on writing and formatting on GitHub as a starting point.
|
||||
|
||||
ROCm documentation adds additional requirements to markdown and rst based files
|
||||
ROCm documentation adds additional requirements to Markdown and RST based files
|
||||
as follows:
|
||||
|
||||
- Level one headers are only used for page titles. There must be only one level
|
||||
1 header per file for both Markdown and Restructured Text.
|
||||
- Pass [markdownlint](https://github.com/markdownlint/markdownlint) check via
|
||||
our automated github action on a Pull Request (PR).
|
||||
our automated GitHub action on a Pull Request (PR).
|
||||
|
||||
## Filenames and folder structure
|
||||
|
||||
Please use snake case for file names. Our documentation follows pitchfork for
|
||||
folder structure. All documentation is in /docs except for special files like
|
||||
the contributing guide in the / folder. All images used in the documentation are
|
||||
place in the /docs/data folder.
|
||||
|
||||
## How to provide feedback for for ROCm documentation
|
||||
|
||||
There are three standard ways to provide feedback for this repository.
|
||||
|
||||
### Pull Request
|
||||
|
||||
All contributions to ROCm documentation should arrive via the
|
||||
[GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)
|
||||
targetting the develop branch of the repository. If you are unable to contribute
|
||||
via the GitHub Flow, feel free to email us. TODO, confirm email address.
|
||||
|
||||
### GitHub Issue
|
||||
|
||||
Issues on existing or absent docs can be filed as [GitHub issues
|
||||
](https://github.com/RadeonOpenCompute/ROCm/issues).
|
||||
|
||||
### Email Feedback
|
||||
Snake case is preferred for file names. Our documentation follows pitchfork for
|
||||
folder structure. All documentation is in `/docs` except for special files like
|
||||
the contributing guide in the `/` folder. All images used in the documentation are
|
||||
place in the `/docs/data` folder.
|
||||
|
||||
## Language and Style
|
||||
|
||||
Adopting Microsoft CPP-Docs guidelines for [Voice and Tone
|
||||
](https://github.com/MicrosoftDocs/cpp-docs/blob/main/styleguide/voice-tone.md).
|
||||
Adopt Microsoft CPP-Docs guidelines for
|
||||
[Voice and Tone](https://github.com/MicrosoftDocs/cpp-docs/blob/main/styleguide/voice-tone.md).
|
||||
|
||||
ROCm documentation templates to be made public shortly. ROCm templates dictate
|
||||
the recommended structure and flow of the documentation. Guidelines on how to
|
||||
@@ -73,174 +54,11 @@ integrate figures, equations, and tables are all based off
|
||||
[MyST](https://myst-parser.readthedocs.io/en/latest/intro.html).
|
||||
|
||||
Font size and selection, page layout, white space control, and other formatting
|
||||
details are controlled via rocm-docs-core, sphinx extention. Please raise issues
|
||||
in rocm-docs-core for any formatting concerns and changes requested.
|
||||
details are controlled via [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core).
|
||||
Raise issues in `rocm-docs-core` for any formatting concerns and changes requested.
|
||||
|
||||
## Building Documentation
|
||||
## More
|
||||
|
||||
While contributing, one may build the documentation locally on the command-line
|
||||
or rely on Continuous Integration for previewing the resulting HTML pages in a
|
||||
browser.
|
||||
|
||||
### Command line documentation builds
|
||||
|
||||
Python versions known to build documentation:
|
||||
|
||||
- 3.8
|
||||
|
||||
To build the docs locally using Python Virtual Environment (`venv`), execute the
|
||||
following commands from the project root:
|
||||
|
||||
```sh
|
||||
python3 -mvenv .venv
|
||||
# Windows
|
||||
.venv/Scripts/python -m pip install -r docs/sphinx/requirements.txt
|
||||
.venv/Scripts/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
|
||||
# Linux
|
||||
.venv/bin/python -m pip install -r docs/sphinx/requirements.txt
|
||||
.venv/bin/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
|
||||
```
|
||||
|
||||
Then open up `_build/html/index.html` in your favorite browser.
|
||||
|
||||
### Pull Requests documentation builds
|
||||
|
||||
When opening a PR to the `develop` branch on GitHub, the page corresponding to
|
||||
the PR (`https://github.com/RadeonOpenCompute/ROCm/pull/<pr_number>`) will have
|
||||
a summary at the bottom. This requires the user be logged in to GitHub.
|
||||
|
||||
- There, click `Show all checks` and `Details` of the Read the Docs pipeline. It
|
||||
will take you to `https://readthedocs.com/projects/advanced-micro-devices-rocm/
|
||||
builds/<some_build_num>/`
|
||||
- The list of commands shown are the exact ones used by CI to produce a render
|
||||
of the documentation.
|
||||
- There, click on the small blue link `View docs` (which is not the same as the
|
||||
bigger button with the same text). It will take you to the built HTML site with
|
||||
a URL of the form `https://
|
||||
advanced-micro-devices-demo--<pr_number>.com.readthedocs.build/projects/alpha/en
|
||||
/<pr_number>/`.
|
||||
|
||||
### Build the docs using VS Code
|
||||
|
||||
One can put together a productive environment to author documentation and also
|
||||
test it locally using VS Code with only a handful of extensions. Even though the
|
||||
extension landscape of VS Code is ever changing, here is one example setup that
|
||||
proved useful at the time of writing. In it, one can change/add content, build a
|
||||
new version of the docs using a single VS Code Task (or hotkey), see all errors/
|
||||
warnings emitted by Sphinx in the Problems pane and immediately see the
|
||||
resulting website show up on a locally serving web server.
|
||||
|
||||
#### Configuring VS Code
|
||||
|
||||
1. Install the following extensions:
|
||||
|
||||
- Python (ms-python.python)
|
||||
- Live Server (ritwickdey.LiveServer)
|
||||
|
||||
2. Add the following entries in `.vscode/settings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"liveServer.settings.root": "/.vscode/build/html",
|
||||
"liveServer.settings.wait": 1000,
|
||||
"python.terminal.activateEnvInCurrentTerminal": true
|
||||
}
|
||||
```
|
||||
|
||||
The settings in order are set for the following reasons:
|
||||
- Sets the root of the output website for live previews. Must be changed
|
||||
alongside the `tasks.json` command.
|
||||
- Tells live server to wait with the update to give time for Sphinx to
|
||||
regenerate site contents and not refresh before all is don. (Empirical value)
|
||||
- Automatic virtual env activation is a nice touch, should you want to build
|
||||
the site from the integrated terminal.
|
||||
|
||||
3. Add the following tasks in `.vscode/tasks.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "Build Docs",
|
||||
"type": "process",
|
||||
"windows": {
|
||||
"command": "${workspaceFolder}/.venv/Scripts/python.exe"
|
||||
},
|
||||
"command": "${workspaceFolder}/.venv/bin/python3",
|
||||
"args": [
|
||||
"-m",
|
||||
"sphinx",
|
||||
"-j",
|
||||
"auto",
|
||||
"-T",
|
||||
"-b",
|
||||
"html",
|
||||
"-d",
|
||||
"${workspaceFolder}/.vscode/build/doctrees",
|
||||
"-D",
|
||||
"language=en",
|
||||
"${workspaceFolder}/docs",
|
||||
"${workspaceFolder}/.vscode/build/html"
|
||||
],
|
||||
"problemMatcher": [
|
||||
{
|
||||
"owner": "sphinx",
|
||||
"fileLocation": "absolute",
|
||||
"pattern": {
|
||||
"regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):(\\d+):\\s+(WARNING|ERROR):\\s+(.*)$",
|
||||
"file": 1,
|
||||
"line": 2,
|
||||
"severity": 3,
|
||||
"message": 4
|
||||
},
|
||||
},
|
||||
{
|
||||
"owner": "sphinx",
|
||||
"fileLocation": "absolute",
|
||||
"pattern": {
|
||||
"regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$",
|
||||
"file": 1,
|
||||
"severity": 2,
|
||||
"message": 3
|
||||
}
|
||||
}
|
||||
],
|
||||
"group": {
|
||||
"kind": "build",
|
||||
"isDefault": true
|
||||
}
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
> (Implementation detail: two problem matchers were needed to be defined,
|
||||
> because VS Code doesn't tolerate some problem information being potentially
|
||||
> absent. While a single regex could match all types of errors, if a capture
|
||||
> group remains empty (the line number doesn't show up in all warning/error
|
||||
> messages) but the `pattern` references said empty capture group, VS Code
|
||||
> discards the message completely.)
|
||||
|
||||
4. Configure Python virtual environment (venv)
|
||||
|
||||
- From the Command Palette, run `Python: Create Environment`
|
||||
- Select `venv` environment and the `docs/sphinx/requirements.txt` file.
|
||||
_(Simply pressing enter while hovering over the file from the dropdown is
|
||||
insufficient, one has to select the radio button with the 'Space' key if
|
||||
using the keyboard.)_
|
||||
|
||||
5. Build the docs
|
||||
|
||||
- Launch the default build Task using either:
|
||||
- a hotkey _(default is 'Ctrl+Shift+B')_ or
|
||||
- by issuing the `Tasks: Run Build Task` from the Command Palette.
|
||||
|
||||
6. Open the live preview
|
||||
|
||||
- Navigate to the output of the site within VS Code, right-click on
|
||||
`.vscode/build/html/index.html` and select `Open with Live Server`. The
|
||||
contents should update on every rebuild without having to refresh the
|
||||
browser.
|
||||
|
||||
<!-- markdownlint-restore -->
|
||||
For more topics, such as submitting feedback and ways to build documentation,
|
||||
see the [Contributing Section](https://rocm.docs.amd.com/en/latest/contributing.html)
|
||||
at [rocm.docs.amd.com](https://rocm.docs.amd.com)
|
||||
|
||||
25
README.md
25
README.md
@@ -1,27 +1,30 @@
|
||||
# AMD ROCm™ Platform
|
||||
|
||||
ROCm™ is an open-source stack for GPU computation. ROCm is primarily Open-Source
|
||||
ROCm is an open-source stack for GPU computation. ROCm is primarily Open-Source
|
||||
Software (OSS) that allows developers the freedom to customize and tailor their
|
||||
GPU software for their own needs while collaborating with a community of other
|
||||
developers, and helping each other find solutions in an agile, flexible, rapid
|
||||
developers, and helping each other find solutions in an agile, flexible, rapid,
|
||||
and secure manner.
|
||||
|
||||
ROCm is a collection of drivers, development tools and APIs enabling GPU
|
||||
programming from the low-level kernel to end-user applications. ROCm is powered
|
||||
by AMD’s Heterogeneous-computing Interface for Portability (HIP), an OSS C++ GPU
|
||||
programming environment and its corresponding runtime. HIP allows ROCm
|
||||
developers to create portable applications on different platforms by deploying
|
||||
code on a range of platforms, from dedicated gaming GPUs to exascale HPC
|
||||
clusters. ROCm supports programming models such as OpenMP and OpenCL, and
|
||||
includes all the necessary OSS compilers, debuggers and libraries. ROCm is fully
|
||||
integrated into ML frameworks such as PyTorch and TensorFlow. ROCm can be
|
||||
programming from the low-level kernel to end-user applications.
|
||||
|
||||
ROCm is powered by AMD’s Heterogeneous-computing Interface for Portability (HIP),
|
||||
an OSS C++ GPU programming environment and its corresponding runtime.
|
||||
HIP allows ROCm developers to create portable applications on different platforms
|
||||
by deploying code on a range of platforms, from dedicated gaming GPUs to exascale
|
||||
High Performance Computing (HPC) clusters.
|
||||
|
||||
ROCm supports programming models such as OpenMP and OpenCL,
|
||||
and includes all the necessary OSS compilers, debuggers, and libraries.
|
||||
ROCm is fully integrated into ML frameworks such as PyTorch and TensorFlow. ROCm can be
|
||||
deployed in many ways, including through the use of containers such as Docker,
|
||||
Spack, and your own build from source.
|
||||
|
||||
ROCm’s goal is to allow our users to maximize their GPU hardware investment.
|
||||
ROCm is designed to help develop, test and deploy GPU accelerated HPC, AI,
|
||||
scientific computing, CAD, and other applications in a free, open-source,
|
||||
integrated and secure software ecosystem.
|
||||
integrated, and secure software ecosystem.
|
||||
|
||||
This repository contains the manifest file for ROCm™ releases, changelogs, and
|
||||
release information. The file default.xml contains information for all
|
||||
|
||||
@@ -5,70 +5,68 @@ Documentation is built using open source toolchains. Contributions to our
|
||||
documentation is encouraged and welcome. As a contributor, please familiarize
|
||||
yourself with our documentation toolchain.
|
||||
|
||||
## ReadTheDocs
|
||||
## `rocm-docs-core`
|
||||
|
||||
[ReadTheDocs](https://docs.readthedocs.io/en/stable/) is our front end for the
|
||||
our documentation. By front end, this is the tool that serves our HTML based
|
||||
documentation to our end users.
|
||||
|
||||
## Doxygen
|
||||
|
||||
[Doxygen](https://www.doxygen.nl/) is the most common inline code documentation
|
||||
standard. ROCm projects are use Doxygen for public API documentation (unless the
|
||||
upstream project is using a different tool).
|
||||
[rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) is an AMD-maintained
|
||||
project that applies customization for our documentation. This
|
||||
project is the tool most ROCm repositories use as part of the documentation
|
||||
build. It is also available as a [pip package on PyPI](https://pypi.org/project/rocm-docs-core/).
|
||||
|
||||
## Sphinx
|
||||
|
||||
[Sphinx](https://www.sphinx-doc.org/en/master/) is a documentation generator
|
||||
originally used for python. It is now widely used in the Open Source community.
|
||||
Originally, sphinx supported RST based documentation. Markdown support is now
|
||||
available. ROCm documentation plans to default to markdown for new projects.
|
||||
Existing projects using RST are under no obligation to convert to markdown. New
|
||||
projects that believe markdown is not suitable should contact the documentation
|
||||
originally used for Python. It is now widely used in the Open Source community.
|
||||
Originally, Sphinx supported reStructuredText (RST) based documentation, but
|
||||
Markdown support is now available.
|
||||
ROCm documentation plans to default to Markdown for new projects.
|
||||
Existing projects using RST are under no obligation to convert to Markdown. New
|
||||
projects that believe Markdown is not suitable should contact the documentation
|
||||
team prior to selecting RST.
|
||||
|
||||
## Read the Docs
|
||||
|
||||
[Read the Docs](https://docs.readthedocs.io/en/stable/) is the service that builds
|
||||
and hosts the HTML documentation generated using Sphinx to our end users.
|
||||
|
||||
## Doxygen
|
||||
|
||||
[Doxygen](https://www.doxygen.nl/) is a documentation generator that extracts
|
||||
information from inline code.
|
||||
ROCm projects typically use Doxygen for public API documentation unless the
|
||||
upstream project uses a different tool.
|
||||
|
||||
### Breathe
|
||||
|
||||
[Breathe](https://www.breathe-doc.org/) is a Sphinx plugin to integrate Doxygen
|
||||
content.
|
||||
|
||||
### MyST
|
||||
|
||||
[Markedly Structured Text (MyST)](https://myst-tools.org/docs/spec) is an extended
|
||||
flavor of Markdown ([CommonMark](https://commonmark.org/)) influenced by reStructuredText (RST) and Sphinx.
|
||||
It is integrated via [`myst-parser`](https://myst-parser.readthedocs.io/en/latest/).
|
||||
A cheat sheet that showcases how to use the MyST syntax is available over at [the Jupyter
|
||||
reference](https://jupyterbook.org/en/stable/reference/cheatsheet.html).
|
||||
|
||||
### Sphinx Theme
|
||||
|
||||
ROCm is using the
|
||||
[Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/en/latest/). This
|
||||
theme is used by Jupyter books. ROCm documentation applies some customization
|
||||
include a header and footer on top of the Sphinx Book Theme. A future custom
|
||||
ROCm theme will be part of our documentation goals.
|
||||
|
||||
### Sphinx Design
|
||||
|
||||
Sphinx Design is an extension for sphinx based websites that add design
|
||||
functionality. Please see the documentation
|
||||
[here](https://sphinx-design.readthedocs.io/en/latest/index.html). ROCm
|
||||
documentation uses sphinx design for grids, cards, and synchronized tabs.
|
||||
Other features may be used in the future.
|
||||
It is integrated into ROCm documentation by the Sphinx extension [`myst-parser`](https://myst-parser.readthedocs.io/en/latest/).
|
||||
A cheat sheet that showcases how to use the MyST syntax is available over at
|
||||
the [Jupyter reference](https://jupyterbook.org/en/stable/reference/cheatsheet.html).
|
||||
|
||||
### Sphinx External TOC
|
||||
|
||||
ROCm uses the
|
||||
[sphinx-external-toc](https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
|
||||
for our navigation. This tool allows a YAML file based left navigation menu. This
|
||||
tool was selected due to its flexibility that allows scripts to operate on the
|
||||
[Sphinx External Table of Contents (TOC)](https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
|
||||
is a Sphinx extension used for ROCm documentation navigation. This tool generates a navigation menu on the left
|
||||
based on a YAML file that specifies the table of contents.
|
||||
It was selected due to its flexibility that allows scripts to operate on the
|
||||
YAML file. Please transition to this file for the project's navigation. You can
|
||||
see the `_toc.yml.in` file in this repository in the docs/sphinx folder for an
|
||||
see the `_toc.yml.in` file in this repository in the `docs/sphinx` folder for an
|
||||
example.
|
||||
|
||||
### Breathe
|
||||
### Sphinx Book Theme
|
||||
|
||||
Sphinx uses [Breathe](https://www.breathe-doc.org/) to integrate Doxygen
|
||||
content.
|
||||
[Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/en/latest/) is a Sphinx theme
|
||||
that defines the base appearance for ROCm documentation.
|
||||
ROCm documentation applies some customization,
|
||||
such as a custom header and footer on top of the Sphinx Book Theme.
|
||||
|
||||
## `rocm-docs-core` pip package
|
||||
### Sphinx Design
|
||||
|
||||
[rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) is an AMD
|
||||
maintained project that applies customization for our documentation. This
|
||||
project is the tool most ROCm repositories will use as part of the documentation
|
||||
build.
|
||||
[Sphinx Design](https://sphinx-design.readthedocs.io/en/latest/index.html) is a Sphinx extension that adds design
|
||||
functionality.
|
||||
ROCm documentation uses Sphinx Design for grids, cards, and synchronized tabs.
|
||||
|
||||
165
docs/contribute/building.md
Normal file
165
docs/contribute/building.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Building Documentation
|
||||
|
||||
While contributing, one may build the documentation locally on the command-line
|
||||
or rely on Continuous Integration for previewing the resulting HTML pages in a
|
||||
browser.
|
||||
|
||||
## Pull Request documentation builds
|
||||
|
||||
When opening a PR to the `develop` branch on GitHub, the page corresponding to
|
||||
the PR (`https://github.com/RadeonOpenCompute/ROCm/pull/<pr_number>`) will have
|
||||
a summary at the bottom. This requires the user be logged in to GitHub.
|
||||
|
||||
- There, click `Show all checks` and `Details` of the Read the Docs pipeline. It
|
||||
will take you to a URL of the form
|
||||
`https://readthedocs.com/projects/advanced-micro-devices-rocm/builds/<some_build_num>/`
|
||||
- The list of commands shown are the exact ones used by CI to produce a render
|
||||
of the documentation.
|
||||
- There, click on the small blue link `View docs` (which is not the same as the
|
||||
bigger button with the same text). It will take you to the built HTML site with
|
||||
a URL of the form
|
||||
`https://advanced-micro-devices-demo--<pr_number>.com.readthedocs.build/projects/alpha/en/<pr_number>/`.
|
||||
|
||||
## Build documentation from the Command Line
|
||||
|
||||
Python versions known to build documentation:
|
||||
|
||||
- 3.8
|
||||
|
||||
To build the docs locally using Python Virtual Environment (`venv`), execute the
|
||||
following commands from the project root:
|
||||
|
||||
```sh
|
||||
python3 -mvenv .venv
|
||||
# Windows
|
||||
.venv/Scripts/python -m pip install -r docs/sphinx/requirements.txt
|
||||
.venv/Scripts/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
|
||||
# Linux
|
||||
.venv/bin/python -m pip install -r docs/sphinx/requirements.txt
|
||||
.venv/bin/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
|
||||
```
|
||||
|
||||
Then open up `_build/html/index.html` in your favorite browser.
|
||||
|
||||
## Build documentation using Visual Studio (VS) Code
|
||||
|
||||
One can put together a productive environment to author documentation and also
|
||||
test it locally using VS Code with only a handful of extensions. Even though the
|
||||
extension landscape of VS Code is ever changing, here is one example setup that
|
||||
proved useful at the time of writing. In it, one can change/add content, build a
|
||||
new version of the docs using a single VS Code Task (or hotkey), see all errors/
|
||||
warnings emitted by Sphinx in the Problems pane and immediately see the
|
||||
resulting website show up on a locally-served web server.
|
||||
|
||||
### Configuring VS Code
|
||||
|
||||
1. Install the following extensions:
|
||||
|
||||
- Python `(ms-python.python)`
|
||||
- Live Server `(ritwickdey.LiveServer)`
|
||||
|
||||
2. Add the following entries in `.vscode/settings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"liveServer.settings.root": "/.vscode/build/html",
|
||||
"liveServer.settings.wait": 1000,
|
||||
"python.terminal.activateEnvInCurrentTerminal": true
|
||||
}
|
||||
```
|
||||
|
||||
The settings above are used for the following reasons:
|
||||
- `liveServer.settings.root`: Sets the root of the output website for live previews. Must be changed
|
||||
alongside the `tasks.json` command.
|
||||
- `liveServer.settings.wait`: Tells live server to wait with the update to give time for Sphinx to
|
||||
regenerate site contents and not refresh before all is done. (Empirical value)
|
||||
- `python.terminal.activateEnvInCurrentTerminal`: Automatic virtual environment activation is a nice touch,
|
||||
should you want to build the site from the integrated terminal.
|
||||
|
||||
3. Add the following tasks in `.vscode/tasks.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "Build Docs",
|
||||
"type": "process",
|
||||
"windows": {
|
||||
"command": "${workspaceFolder}/.venv/Scripts/python.exe"
|
||||
},
|
||||
"command": "${workspaceFolder}/.venv/bin/python3",
|
||||
"args": [
|
||||
"-m",
|
||||
"sphinx",
|
||||
"-j",
|
||||
"auto",
|
||||
"-T",
|
||||
"-b",
|
||||
"html",
|
||||
"-d",
|
||||
"${workspaceFolder}/.vscode/build/doctrees",
|
||||
"-D",
|
||||
"language=en",
|
||||
"${workspaceFolder}/docs",
|
||||
"${workspaceFolder}/.vscode/build/html"
|
||||
],
|
||||
"problemMatcher": [
|
||||
{
|
||||
"owner": "sphinx",
|
||||
"fileLocation": "absolute",
|
||||
"pattern": {
|
||||
"regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):(\\d+):\\s+(WARNING|ERROR):\\s+(.*)$",
|
||||
"file": 1,
|
||||
"line": 2,
|
||||
"severity": 3,
|
||||
"message": 4
|
||||
},
|
||||
},
|
||||
{
|
||||
"owner": "sphinx",
|
||||
"fileLocation": "absolute",
|
||||
"pattern": {
|
||||
"regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$",
|
||||
"file": 1,
|
||||
"severity": 2,
|
||||
"message": 3
|
||||
}
|
||||
}
|
||||
],
|
||||
"group": {
|
||||
"kind": "build",
|
||||
"isDefault": true
|
||||
}
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
> (Implementation detail: two problem matchers were needed to be defined,
|
||||
> because VS Code doesn't tolerate some problem information being potentially
|
||||
> absent. While a single regex could match all types of errors, if a capture
|
||||
> group remains empty (the line number doesn't show up in all warning/error
|
||||
> messages) but the `pattern` references said empty capture group, VS Code
|
||||
> discards the message completely.)
|
||||
|
||||
4. Configure Python virtual environment (`venv`)
|
||||
|
||||
- From the Command Palette, run `Python: Create Environment`
|
||||
- Select `venv` environment and the `docs/sphinx/requirements.txt` file.
|
||||
_(Simply pressing enter while hovering over the file from the drop down is
|
||||
insufficient, one has to select the radio button with the 'Space' key if
|
||||
using the keyboard.)_
|
||||
|
||||
5. Build the docs
|
||||
|
||||
- Launch the default build Task using either:
|
||||
- a hotkey _(default is `Ctrl+Shift+B`)_ or
|
||||
- by issuing the `Tasks: Run Build Task` from the Command Palette.
|
||||
|
||||
6. Open the live preview
|
||||
|
||||
- Navigate to the output of the site within VS Code, right-click on
|
||||
`.vscode/build/html/index.html` and select `Open with Live Server`. The
|
||||
contents should update on every rebuild without having to refresh the
|
||||
browser.
|
||||
27
docs/contribute/feedback.md
Normal file
27
docs/contribute/feedback.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# How to provide feedback for for ROCm documentation
|
||||
|
||||
There are four standard ways to provide feedback for this repository.
|
||||
|
||||
## Pull Request
|
||||
|
||||
All contributions to ROCm documentation should arrive via the
|
||||
[GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)
|
||||
targeting the develop branch of the repository. If you are unable to contribute
|
||||
via the GitHub Flow, feel free to email us.
|
||||
|
||||
## GitHub Discussions
|
||||
|
||||
To ask questions or view answers to frequently asked questions, refer to
|
||||
[GitHub Discussions](https://github.com/RadeonOpenCompute/ROCm/discussions).
|
||||
On GitHub Discussions, in addition to asking and answering questions,
|
||||
members can share updates, have open-ended conversations,
|
||||
and follow along on via public announcements.
|
||||
|
||||
## GitHub Issue
|
||||
|
||||
Issues on existing or absent docs can be filed as
|
||||
[GitHub Issues](https://github.com/RadeonOpenCompute/ROCm/issues).
|
||||
|
||||
## Email
|
||||
|
||||
Send other feedback or questions to [rocm-feedback@amd.com](rocm-feedback@amd.com)
|
||||
23
docs/rocm.md
23
docs/rocm.md
@@ -3,22 +3,25 @@
|
||||
ROCm is an open-source stack for GPU computation. ROCm is primarily Open-Source
|
||||
Software (OSS) that allows developers the freedom to customize and tailor their
|
||||
GPU software for their own needs while collaborating with a community of other
|
||||
developers, and helping each other find solutions in an agile, flexible, rapid
|
||||
developers, and helping each other find solutions in an agile, flexible, rapid,
|
||||
and secure manner.
|
||||
|
||||
ROCm is a collection of drivers, development tools and APIs enabling GPU
|
||||
programming from the low-level kernel to end-user applications. ROCm is powered
|
||||
by AMD’s Heterogeneous-computing Interface for Portability (HIP), an OSS C++ GPU
|
||||
programming environment and its corresponding runtime. HIP allows ROCm
|
||||
developers to create portable applications on different platforms by deploying
|
||||
code on a range of platforms, from dedicated gaming GPUs to exascale HPC
|
||||
clusters. ROCm supports programming models such as OpenMP and OpenCL, and
|
||||
includes all the necessary OSS compilers, debuggers and libraries. ROCm is fully
|
||||
integrated into ML frameworks such as PyTorch and TensorFlow. ROCm can be
|
||||
programming from the low-level kernel to end-user applications.
|
||||
|
||||
ROCm is powered by AMD’s Heterogeneous-computing Interface for Portability (HIP),
|
||||
an OSS C++ GPU programming environment and its corresponding runtime.
|
||||
HIP allows ROCm developers to create portable applications on different platforms
|
||||
by deploying code on a range of platforms, from dedicated gaming GPUs to exascale
|
||||
High Performance Computing (HPC) clusters.
|
||||
|
||||
ROCm supports programming models such as OpenMP and OpenCL,
|
||||
and includes all the necessary OSS compilers, debuggers, and libraries.
|
||||
ROCm is fully integrated into ML frameworks such as PyTorch and TensorFlow. ROCm can be
|
||||
deployed in many ways, including through the use of containers such as Docker,
|
||||
Spack, and your own build from source.
|
||||
|
||||
ROCm’s goal is to allow our users to maximize their GPU hardware investment.
|
||||
ROCm is designed to help develop, test and deploy GPU accelerated HPC, AI,
|
||||
scientific computing, CAD, and other applications in a free, open-source,
|
||||
integrated and secure software ecosystem.
|
||||
integrated, and secure software ecosystem.
|
||||
|
||||
@@ -233,3 +233,7 @@ subtrees:
|
||||
entries:
|
||||
- file: about
|
||||
- file: contributing
|
||||
subtrees:
|
||||
- entries:
|
||||
- file: contribute/building.md
|
||||
- file: contribute/feedback.md
|
||||
|
||||
Reference in New Issue
Block a user