github/ROCm
1
1
Fork 0
mirror of https://github.com/ROCm/ROCm.git synced 2026-01-09 14:48:06 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update style guidelines (#2542)

Browse Source
This commit is contained in:
Lisa
2023-10-12 13:50:15 -06:00
committed by GitHub
parent 4b7775d264
commit c6e2856822
8 changed files with 321 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.wordlist.txt
View File

@@ -46,6 +46,7 @@ cd
CDNA CDNA
CentOS CentOS
centric centric
changelog
chiplet chiplet
CIFAR CIFAR
CLI CLI
@@ -361,6 +362,7 @@ repos
Req Req
req req
resampling resampling
RST
reStructuredText reStructuredText
RHEL RHEL
Rickle Rickle

265
CONTRIBUTING.md
View File

@@ -1,69 +1,228 @@
# Contributing to ROCm documentation # Contributing to ROCm documentation
AMD values and encourages the ROCm community to contribute to our code and AMD values and encourages contributions to our code and documentation. If you choose to
documentation. This repository is focused on ROCm documentation and this contribute, we encourage you to be polite and respectful. Improving documentation is a long-term
contribution guide describes the recommended method for creating and modifying our process, to which we are dedicated.
documentation.
While interacting with ROCm Documentation, we encourage you to be polite and If you have issues when trying to contribute, refer to the
respectful in your contributions, content or otherwise. Authors, maintainers of [discussions](https://github.com/RadeonOpenCompute/ROCm/discussions) page in our GitHub
these docs act on good intentions and to the best of their knowledge. repository.
Keep that in mind while you engage. Should you have issues with contributing
itself, refer to
[discussions](https://github.com/RadeonOpenCompute/ROCm/discussions) on the
GitHub repository.
For additional information on documentation functionalities, ## Folder structure and naming convention
see the user and developer guides for rocm-docs-core
at {doc}`rocm-docs-core documentation <rocm-docs-core:index>`.
## Supported formats 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
(`/`) folder.
Our documentation includes both Markdown and RST files. Markdown is encouraged All images are stored in the `/docs/data` folder. An image's file path mirrors that of the documentation
over RST due to the lower barrier to participation. GitHub-flavored Markdown is preferred file where it is used.
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 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 Our naming structure uses kebab case; for example, `my-file-name.rst`.
as follows:
* Level one headers are only used for page titles. There must be only one level ## Supported formats and syntax
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).
See the {doc}`rocm-docs-core linting user guide <rocm-docs-core:user_guide/linting>` for more details.
## Filenames and folder structure Our documentation includes both Markdown and RST files. We are gradually transitioning existing
Markdown to RST in order to more effectively meet our documentation needs. When contributing,
RST is preferred; if you must use Markdown, use GitHub-flavored Markdown.
Please use kebab-case (all lower case letters and dashes instead of spaces) We use [Sphinx Design](https://sphinx-design.readthedocs.io/en/latest/index.html) syntax and compile
for file names. For example, `example-file-name.md`. our API references using [Doxygen](https://www.doxygen.nl/).
Our documentation follows Pitchfork for folder structure.
All documentation is in `/docs` except for special files like The following table shows some common documentation components and the syntax convention we
the contributing guide in the `/` folder. All images used in the documentation are use for each:
placed in the `/docs/data` folder.
<table>
<tr>
<th>Component</th>
<th>RST syntax</th>
</tr>
<tr>
<td>Code blocks</td>
<td>
```rst
.. code-block:: language-name
My code block.
```
</td>
</tr>
<tr>
<td>Cross-referencing internal files</td>
<td>
```rst
:doc:`Title <../path/to/file/filename>`
```
</td>
</tr>
<tr>
<td>External links</td>
<td>
```rst
`link name <URL>`_
```
</td>
</tr>
<tr>
<tr>
<td>Headings</td>
<td>
```rst
******************
Chapter title (H1)
******************
Section title (H2)
===============
Subsection title (H3)
---------------------
Sub-subsection title (H4)
^^^^^^^^^^^^^^^^^^^^
```
</td>
</tr>
<tr>
<td>Images</td>
<td>
```rst
.. image:: image1.png
```
</td>
</tr>
<tr>
<td>Internal links</td>
<td>
```rst
1. Add a tag to the section you want to reference:
.. _my-section-tag: section-1
Section 1
==========
2. Link to your tag:
As shown in :ref:`section-1`.
```
</td>
</tr>
<tr>
<tr>
<td>Lists</td>
<td>
```rst
# Ordered (numbered) list item
* Unordered (bulleted) list item
```
</td>
</tr>
<tr>
<tr>
<td>Math (block)</td>
<td>
```rst
.. math::
A = \begin{pmatrix}
0.0 & 1.0 & 1.0 & 3.0 \\
4.0 & 5.0 & 6.0 & 7.0 \\
\end{pmatrix}
```
</td>
</tr>
<tr>
<td>Math (inline)</td>
<td>
```rst
:math:`2 \times 2 `
```
</td>
</tr>
<tr>
<td>Notes</td>
<td>
```rst
.. note::
My note here.
```
</td>
</tr>
<tr>
<td>Tables</td>
<td>
```rst
.. csv-table:: Optional title here
:widths: 30, 70 #optional column widths
:header: "entry1 header", "entry2 header"
"entry1", "entry2"
```
</td>
</tr>
</table>
## Language and style ## Language and style
Adopt Microsoft CPP-Docs guidelines for We use the
[Voice and Tone](https://github.com/MicrosoftDocs/cpp-docs/blob/main/styleguide/voice-tone.md). [Google developer documentation style guide](https://developers.google.com/style/highlights) to
guide our content.
ROCm documentation templates to be made public shortly. ROCm templates dictate Font size and type, page layout, white space control, and other formatting
the recommended structure and flow of the documentation. Guidelines on how to details are controlled via
integrate figures, equations, and tables are all based off [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core). If you want to notify us
[MyST](https://myst-parser.readthedocs.io/en/latest/intro.html). of any formatting issues, create a pull request in our
[rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) GitHub repository.
Font size and selection, page layout, white space control, and other formatting ## Building our documentation
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.
## More To learn how to build our documentation, refer to
[Building documentation](./docs/contribute/building.md).
For more topics, such as submitting feedback and ways to build documentation, refer to [Building documentation](./building.md) and [How to provide feedback for ROCm documentation](./feedback.md).

20
README.md
View File

@@ -21,20 +21,20 @@ source software compilers, debuggers, and libraries. ROCm is fully integrated in
## ROCm documentation ## ROCm documentation
The ROCm Documentation site is [rocm.docs.amd.com](https://rocm.docs.amd.com).
Source code for the documentation is located in the docs folder of most repositories that are part of
ROCm.
This repository contains the manifest file for ROCm releases, changelogs, and release information. This repository contains the manifest file for ROCm releases, changelogs, and release information.
The file `default.xml` contains information for all repositories and the associated commit used to build
the current ROCm release.
The `default.xml` file uses the repo Manifest Format. The `default.xml` file contains information for all repositories and the associated commit used to build
the current ROCm release; `default.xml` uses the Manifest Format repository.
The develop branch of this repository contains content for the next ROCm release. Source code for our documentation is located in the `/docs` folder of most ROCm repositories. The
`develop` branch of our repositories contains content for the next ROCm release.
### How to build documentation via Sphinx The ROCm documentation homepage is [rocm.docs.amd.com](https://rocm.docs.amd.com).
### Building our documentation
For a quick-start build, use the following code. For more options and detail, refer to
[Building documentation](./docs/contribute/building.md).
```bash ```bash
cd docs cd docs

2
RELEASE.md
View File

@@ -11,7 +11,7 @@
<!-- spellcheck-disable --> <!-- spellcheck-disable -->
The release notes for the ROCm platform. Welcome to the release notes for the ROCm platform.
------------------- -------------------

2
docs/about/release-notes.md
View File

@@ -11,7 +11,7 @@
<!-- spellcheck-disable --> <!-- spellcheck-disable -->
The release notes for the ROCm platform. Welcome to the release notes for the ROCm platform.
------------------- -------------------

206
docs/contribute/building.md
View File

@@ -1,138 +1,125 @@
# Building documentation # Building documentation
While contributing, one may build the documentation locally on the command line You can build our documentation via GitHub (in a pull request) or locally (using the command line or
or rely on Continuous Integration for previewing the resulting HTML pages in a Visual Studio (VS) Code.
browser.
## Pull request documentation builds ## GitHub
When opening a PR to the `develop` branch on GitHub, the page corresponding to If you open a pull request on the `develop` branch of a ROCm repository and scroll to the bottom of
the PR (`https://github.com/RadeonOpenCompute/ROCm/pull/<pr_number>`) will have the page, there is a summary panel. Next to the line
a summary at the bottom. This requires the user be logged in to GitHub. `docs/readthedocs.com:advanced-micro-devices-demo`, there is a `Details` link. If you click this, it takes
you to the Read the Docs build for your pull request.
* There, click `Show all checks` and `Details` of the Read the Docs pipeline. It ![Screenshot of the GitHub documentation build link](../data/contribute/github-docs-build.png)
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 If you don't see this line, click `Show all checks` to get an itemized view.
Python versions known to build documentation: ## Command line
* 3.8 You can build our documentation via the command line using Python. We use Python 3.8; other
versions may not support the build.
To build the docs locally using Python Virtual Environment (`venv`), execute the Use the Python Virtual Environment (`venv`) and run the following commands from the project root:
following commands from the project root:
```sh ```sh
python3 -mvenv .venv python3 -mvenv .venv
# Windows # Windows
.venv/Scripts/python -m pip install -r docs/sphinx/requirements.txt .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 .venv/Scripts/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
# Linux # Linux
.venv/bin/python -m pip install -r docs/sphinx/requirements.txt .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 .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. Navigate to `_build/html/index.html` and open this file in a web browser.
## Build documentation using Visual Studio Code ## Visual Studio Code
One can put together a productive environment to author documentation and also With the help of a few extensions, you can create a productive environment to author and test
test it locally using Visual Studio (VS) Code with only a handful of extensions. Even though the documentation locally using Visual Studio (VS) Code. Follow these steps to configure VS Code:
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 required extensions:
1. Install the following extensions: * Python: `(ms-python.python)`
* Python `(ms-python.python)` * Live Server: `(ritwickdey.LiveServer)`
* Live Server `(ritwickdey.LiveServer)`
2. Add the following entries in `.vscode/settings.json` 2. Add the following entries to `.vscode/settings.json`.
```json ```json
{ {
"liveServer.settings.root": "/.vscode/build/html", "liveServer.settings.root": "/.vscode/build/html",
"liveServer.settings.wait": 1000, "liveServer.settings.wait": 1000,
"python.terminal.activateEnvInCurrentTerminal": true "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 * `liveServer.settings.root`: Sets the root of the output website for live previews. Must be changed
alongside the `tasks.json` command. alongside the `tasks.json` command.
* `liveServer.settings.wait`: Tells live server to wait with the update to give time for Sphinx to * `liveServer.settings.wait`: Tells the live server to wait with the update in order to give Sphinx time to
regenerate site contents and not refresh before all is done. (Empirical value) regenerate the site contents and not refresh before the build is complete.
* `python.terminal.activateEnvInCurrentTerminal`: Automatic virtual environment activation is a nice touch, * `python.terminal.activateEnvInCurrentTerminal`: Activates the automatic virtual environment, so you
should you want to build the site from the integrated terminal. can build the site from the integrated terminal.
3. Add the following tasks in `.vscode/tasks.json` 3. Add the following tasks to `.vscode/tasks.json`.
```json ```json
{ {
"version": "2.0.0", "version": "2.0.0",
"tasks": [ "tasks": [
{ {
"label": "Build Docs", "label": "Build Docs",
"type": "process", "type": "process",
"windows": { "windows": {
"command": "${workspaceFolder}/.venv/Scripts/python.exe" "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
},
}, },
{ "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", "owner": "sphinx",
"fileLocation": "absolute", "fileLocation": "absolute",
"pattern": { "pattern": {
"regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$", "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$",
"file": 1, "file": 1,
"severity": 2, "severity": 2,
"message": 3 "message": 3
}
} }
],
"group": {
"kind": "build",
"isDefault": true
} }
],
"group": {
"kind": "build",
"isDefault": true
} }
}, ]
], }
}
``` ```
> (Implementation detail: two problem matchers were needed to be defined, > (Implementation detail: two problem matchers were needed to be defined,
@@ -142,23 +129,20 @@ resulting website show up on a locally-served web server.
> messages) but the `pattern` references said empty capture group, VS Code > messages) but the `pattern` references said empty capture group, VS Code
> discards the message completely.) > discards the message completely.)
4. Configure Python virtual environment (`venv`) 4. Configure the Python virtual environment (`venv`).
* From the Command Palette, run `Python: Create Environment` From the Command Palette, run `Python: Create Environment`. Select `venv` environment and
* Select `venv` environment and the `docs/sphinx/requirements.txt` file. `docs/sphinx/requirements.txt`.
_(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 5. Build the docs.
* Launch the default build Task using either: Launch the default build task using one of the following options:
* a hotkey _(default is `Ctrl+Shift+B`)_ or
* by issuing the `Tasks: Run Build Task` from the Command Palette.
6. Open the live preview * A hotkey (the default is `Ctrl+Shift+B`)
* Issuing the `Tasks: Run Build Task` from the Command Palette
* Navigate to the output of the site within VS Code, right-click on 6. Open the live preview.
`.vscode/build/html/index.html` and select `Open with Live Server`. The
contents should update on every rebuild without having to refresh the Navigate to the site output within VS Code: right-click on `.vscode/build/html/index.html` and
browser. select `Open with Live Server`. The contents should update on every rebuild without having to
refresh the browser.

69
docs/contribute/index.md
View File

@@ -1,69 +0,0 @@
# Contributing to ROCm documentation
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 recommended method for creating and modifying our
documentation.
While interacting with ROCm Documentation, we encourage you to be polite and
respectful in your contributions, content or otherwise. Authors, maintainers of
these docs act on good intentions and to the best of their knowledge.
Keep that in mind while you engage. Should you have issues with contributing
itself, refer to
[discussions](https://github.com/RadeonOpenCompute/ROCm/discussions) on the
GitHub repository.
For additional information on documentation functionalities,
see the user and developer guides for rocm-docs-core
at {doc}`rocm-docs-core documentation <rocm-docs-core:index>`.
## 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 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 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
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).
See the {doc}`rocm-docs-core linting user guide <rocm-docs-core:user_guide/linting>` for more details.
## Filenames and folder structure
Please use kebab-case (all lower case letters and dashes instead of spaces)
for file names. For example, `example-file-name.md`.
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
placed in the `/docs/data` folder.
## Language and style
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
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](https://github.com/RadeonOpenCompute/rocm-docs-core).
Raise issues in `rocm-docs-core` for any formatting concerns and changes requested.
## More
For more topics, such as submitting feedback and ways to build documentation, refer to [Building documentation](./building.md) and [How to provide feedback for ROCm documentation](./feedback.md).

BIN
docs/data/contribute/github-docs-build.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB