update contributing section & update card images (#2865)

This commit is contained in:
Lisa
2024-02-07 09:31:45 -07:00
committed by GitHub
parent 4825afa951
commit 8bbd51376d
40 changed files with 213 additions and 121 deletions

1
.gitignore vendored
View File

@@ -14,6 +14,5 @@ _readthedocs/
# avoid duplicating contributing.md due to conf.py
docs/CHANGELOG.md
docs/contribute/index.md
docs/about/release-notes.md
docs/about/CHANGELOG.md

View File

@@ -527,6 +527,7 @@ unstacking
unswitching
untrusted
untuned
upvote
USM
UTCL
UTIL

View File

@@ -21,7 +21,6 @@ for template in templates:
with open(os.path.splitext(template)[0], 'w') as file:
file.write(rendered)
shutil.copy2('../CONTRIBUTING.md','./contribute/index.md')
shutil.copy2('../RELEASE.md','./about/release-notes.md')
# Keep capitalization due to similar linking on GitHub's markdown preview.
shutil.copy2('../CHANGELOG.md','./about/CHANGELOG.md')

View File

@@ -31,11 +31,6 @@ Use the Python Virtual Environment (`venv`) and run the following commands from
```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
```
@@ -129,12 +124,12 @@ documentation locally using Visual Studio (VS) Code. Follow these steps to confi
}
```
> (Implementation detail: two problem matchers were needed to be defined,
> 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.)
> discards the message completely.
4. Configure the Python virtual environment (`venv`).

View File

@@ -0,0 +1,127 @@
<head>
<meta charset="UTF-8">
<meta name="description" content="Contributing to ROCm">
<meta name="keywords" content="ROCm, contributing, contribute, maintainer, contributor">
</head>
# Contribute to ROCm documentation
All ROCm projects are GitHub-based, so if you want to contribute, you can do so by:
* [Submitting a pull request (PR) in the appropriate GitHub repository](#submit-a-pull-request)
* [Creating an issue in the appropriate GitHub repository](#create-an-issue)
* [Suggesting a new feature](#suggest-a-new-feature)
```{note}
Because some of our components are inherited from external projects (such as
[LLVM](https://github.com/ROCm/llvm-project) and
[Kernel driver](https://github.com/ROCm/ROCK-Kernel-Driver)), they use project-specific
contribution guidelines and workflow.
```
## Submit a pull request
```{important}
By creating a PR, you agree to allow your contribution to be licensed under the terms of the
LICENSE.txt file in the corresponding repository. Different repositories may use different licenses.
```
1. Identify the repository and the file you want to update. For example, to update this page, you would
need to modify content located in this file:
`https://github.com/ROCm/ROCm/blob/develop/docs/contribute/contributing.md`
2. (optional, but recommended) Fork the repository.
3. Clone the repository locally and (optionally) add your fork. Select the green 'Code' button and copy
the URL (e.g., `git@github.com:ROCm/ROCm.git`).
* From your terminal, run:
```bash
git clone git@github.com:ROCm/ROCm.git
```
* Add your fork to this local copy of the repository. Run:
```bash
git add remote <name-of-my-fork> <git@github.com:my-username/ROCm.git>
```
To get the URL of your fork, go to your GitHub profile, select the fork and click the green 'Code'
button (the same process you followed to get the main GitHub repository URL).
4. Check out the **develop** branch and run 'git pull' (and/or 'git pull origin develop' to ensure your
local version has the most recent content.
5. Create a new branch.
```bash
git checkout -b my-new-branch
```
6. Make your changes locally using your preferred code editor. If you're editing documentation, follow
the guidelines listed on the
[documentation structure](./doc-structure.md) page.
7. (optional) We recommend running a local test build to ensure the content looks the way you expect.
In your terminal, run:
```bash
python3 -mvenv .venv
.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
```
The build files are located in the `docs/_build` folder. To preview your build, open the index file
(`docs/_build/html/index.html`) file. For more information, see
[Building documentation](building.md). To learn
more about our build tools, see
[Documentation toolchain](toolchain.md).
8. Commit your changes and push them to GitHub. Run:
```bash
git add <path-to-my-modified-file> # to add all modified files, you can use: git add .
git commit -m "my-updates"
git push <name-of-my-fork>
```
After pushing, you will get a GitHub link in the terminal output. Copy this link and paste it into a
browser to create your PR.
## Create an issue
1. To create a new GitHub issue, select the 'Issues' tab in the appropriate repository
(e.g., https://github.com/ROCm/ROCm/issues).
2. Use the search bar to make sure the issue doesn't already exist.
3. If your issue is not already listed, select the green 'New issue' button to the right of the page. Select
the type of issue and fill in the resulting template.
### General issue guidelines
* Use your best judgement for issue creation. If your issue is already listed, upvote the issue and
comment or post to provide additional details, such as how you reproduced this issue.
* If you're not sure if your issue is the same, err on the side of caution and file your issue.
You can add a comment to include the issue number (and link) for the similar issue. If we evaluate
your issue as being the same as the existing issue, we'll close the duplicate.
* If your issue doesn't exist, use the issue template to file a new issue.
* When filing an issue, be sure to provide as much information as possible, including script output so
we can collect information about your configuration. This helps reduce the time required to
reproduce your issue.
* Check your issue regularly, as we may require additional information to successfully reproduce the
issue.
## Suggest a new feature
Use the [GitHub Discussion forum](https://github.com/ROCm/ROCm/discussions)
(Ideas category) to propose new features. Our maintainers are happy to provide direction and
feedback on feature development.
## Future development workflow
The current ROCm development workflow is GitHub-based. If, in the future, we change this platform,
the tools and links may change. In this instance, we will update contribution guidelines accordingly.

View File

@@ -1,14 +1,4 @@
# Contributing to ROCm documentation
AMD values and encourages contributions to our code and documentation. If you choose to
contribute, we encourage you to be polite and respectful. Improving documentation is a long-term
process, to which we are dedicated.
If you have issues when trying to contribute, refer to the
[discussions](https://github.com/RadeonOpenCompute/ROCm/discussions) page in our GitHub
repository.
## Folder structure and naming convention
# Documentation structure
Our documentation follows the Pitchfork folder structure. Most documentation files are stored in the
`/docs` folder. Some special files (such as release, contributing, and changelog) are stored in the root

View File

@@ -4,9 +4,9 @@
<meta name="keywords" content="documentation, pull request, GitHub, AMD, ROCm">
</head>
# Providing feedback for ROCm documentation
# Providing feedback
There are four standard ways to provide feedback for this repository.
There are four standard ways to provide feedback on this repository.
## Pull request
@@ -15,6 +15,9 @@ All contributions to ROCm documentation should arrive via the
targeting the develop branch of the repository. If you are unable to contribute
via the GitHub Flow, feel free to email us at [rocm-feedback@amd.com](mailto:rocm-feedback@amd.com?subject=Documentation%20Feedback).
For more in-depth information on creating a pull request (PR), see
[Contributing](./contributing.md).
## GitHub discussions
To ask questions or view answers to frequently asked questions, refer to
@@ -25,8 +28,8 @@ 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).
Issues on existing or absent documentation can be filed in
[GitHub Issues](https://github.com/ROCm/ROCm/issues).
## Email

View File

@@ -11,67 +11,55 @@ Our documentation relies on several open source toolchains and sites.
## `rocm-docs-core`
[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/).
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/).
See the user and developer guides for rocm-docs-core at {doc}`rocm-docs-core documentation<rocm-docs-core:index>`.
See the user and developer guides for rocm-docs-core at
{doc}`rocm-docs-core documentation<rocm-docs-core:index>`.
## 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 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 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](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.
### Sphinx External ToC
[Sphinx External 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
example.
[Sphinx External 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 (`_toc.yml.in`) that contains the table of contents.
### Sphinx-book-theme
[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.
[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.
### Sphinx design
### Sphinx Design
[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.
[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.
## 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's integrated into ROCm documentation by the Sphinx extension
[`myst-parser`](https://myst-parser.readthedocs.io/en/latest/).
A MyST syntax cheat sheet is available on the [Jupyter reference](https://jupyterbook.org/en/stable/reference/cheatsheet.html) site.
## 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.

Binary file not shown.

After

Width:  |  Height:  |  Size: 201 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 204 KiB

BIN
docs/data/banner-howto.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 201 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 199 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 202 KiB

BIN
docs/data/banner-text.xcf Normal file

Binary file not shown.

BIN
docs/data/banner.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.1 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 939 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 537 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 292 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.3 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.6 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.5 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.5 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 114 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 110 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 228 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 796 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 310 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 789 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 801 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 102 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 102 KiB

View File

@@ -15,7 +15,7 @@ resources to learn more about our products and what we support:
You can install ROCm on our Radeon™, Radeon Pro™, and Instinct™ GPUs. If you're using Radeon
GPUs, we recommend reading the
{doc}`Radeon-specific ROCm documentation<radeon:index>`
{doc}`Radeon-specific ROCm documentation<radeon:index>`.
Our documentation is organized into the following categories:
@@ -24,10 +24,7 @@ Our documentation is organized into the following categories:
:::{grid-item-card}
:padding: 2
**Installation**
Installation guides
^^^
:img-top: ./data/banner-installation.png
* Linux
* {doc}`Quick-start (Linux)<rocm-install-on-linux:tutorial/quick-start>`
@@ -41,15 +38,11 @@ Installation guides
* {doc}`TensorFlow for ROCm<rocm-install-on-linux:how-to/3rd-party/tensorflow-install>`
* {doc}`MAGMA for ROCm<rocm-install-on-linux:how-to/3rd-party/magma-install>`
* {doc}`ROCm & Spack<rocm-install-on-linux:how-to/spack>`
:::
:::{grid-item-card}
:padding: 2
**Compatibility & support**
ROCm compatibility information
^^^
:img-top: ./data/banner-compatibility.png
* {doc}`System requirements (Linux)<rocm-install-on-linux:reference/system-requirements>`
* {doc}`System requirements (Windows)<rocm-install-on-windows:reference/system-requirements>`
@@ -58,15 +51,30 @@ ROCm compatibility information
* {doc}`Docker<rocm-install-on-linux:reference/docker-image-support-matrix>`
* [OpenMP](./about/compatibility/openmp.md)
{doc}`ROCm on Radeon GPUs<radeon:index>`
:::
:::{grid-item-card}
:padding: 2
**How-to**
:img-top: ./data/banner-reference.png
Task-oriented walkthroughs
^^^
* [API Libraries & tools](./reference/library-index.md)
* Libraries:
* Artificial intelligence
* C++ primitives
* Communication
* Fast Fourier transforms
* HIP
* Linear algebra
* Random number generators
* Tools for:
* Development
* Performance analysis
* System
:::
:::{grid-item-card}
:padding: 2
:img-top: ./data/banner-howto.png
* [System tuning for various architectures](./how-to/tuning-guides.md)
* [MI100](./how-to/tuning-guides/mi100.md)
@@ -76,26 +84,11 @@ Task-oriented walkthroughs
* [GPU-enabled MPI](./how-to/gpu-enabled-mpi.rst)
* [System level debugging](./how-to/system-debugging.md)
* [GitHub examples](https://github.com/amd/rocm-examples)
:::
:::{grid-item-card}
:padding: 2
**Reference**
Collated information
^^^
* [API Libraries](./reference/library-index.md)
:::
:::{grid-item-card}
:padding: 2
**Conceptual**
Topic overviews & background information
^^^
:img-top: ./data/banner-conceptual.png
* [GPU architecture](./conceptual/gpu-arch.md)
* [MI100](./conceptual/gpu-arch/mi100.md)
@@ -111,13 +104,12 @@ Topic overviews & background information
* [Inception v3 with PyTorch](./conceptual/ai-pytorch-inception.md)
* [Inference optimization with MIGraphX](./conceptual/ai-migraphx-optimization.md)
* [OpenMP support in ROCm](./about/compatibility/openmp.md)
:::
::::
We welcome collaboration! If you'd like to contribute to our documentation, you can find instructions
on our [Contribute to ROCm docs](./contribute/index.md) page. Known issues are listed on
on our [Contribute to ROCm docs](./contribute/contributing.md) page. Known issues are listed on
[GitHub](https://github.com/RadeonOpenCompute/ROCm/labels/Verified%20Issue).
Licensing information for all ROCm components is listed on our [Licensing](./about/license.md) page.

View File

@@ -139,7 +139,7 @@
::::
We welcome collaboration! If you'd like to contribute to our documentation, you can find instructions
on our [Contribute to ROCm docs](../contribute/index.md) page. Known issues are listed on
on our [Contribute to ROCm docs](../contribute/contributing.md) page. Known issues are listed on
[GitHub](https://github.com/RadeonOpenCompute/ROCm/labels/Verified%20Issue).
Licensing information for all ROCm components is listed on our [Licensing](../about/license.md) page.

View File

@@ -103,20 +103,18 @@ subtrees:
- caption: Contribute
entries:
- file: contribute/index.md
title: Contribute to ROCm
- file: contribute/contributing.md
title: Contribute to ROCm docs
subtrees:
- entries:
- file: contribute/contribute-docs.md
title: Contribute to ROCm docs
subtrees:
- entries:
- file: contribute/toolchain.md
title: Documentation tools
- file: contribute/building.md
title: Building documentation
- file: contribute/feedback.md
title: Provide feedback
- file: contribute/doc-structure.md
title: Documentation structure
- file: contribute/toolchain.md
title: Documentation toolchain
- file: contribute/building.md
title: Build our documentation
- file: contribute/feedback.md
title: Provide feedback
- file: about/license.md
title: ROCm license