github/ROCm
1
1
Fork 0
mirror of https://github.com/ROCm/ROCm.git synced 2026-01-09 22:58:17 -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
CentOS
centric
changelog
chiplet
CIFAR
CLI
@@ -361,6 +362,7 @@ repos
Req
req
resampling
RST
reStructuredText
RHEL
Rickle

265
CONTRIBUTING.md
View File

@@ -1,69 +1,228 @@
# 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.
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.
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.
If you have issues when trying to contribute, refer to the
[discussions](https://github.com/RadeonOpenCompute/ROCm/discussions) page in our 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>`.
## Folder structure and naming convention
## 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
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.
All images are stored in the `/docs/data` folder. An image's file path mirrors that of the documentation
file where it is used.
ROCm documentation adds additional requirements to Markdown and RST based files
as follows:
Our naming structure uses kebab case; for example, `my-file-name.rst`.
* 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.
## Supported formats and syntax
## 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)
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.
We use [Sphinx Design](https://sphinx-design.readthedocs.io/en/latest/index.html) syntax and compile
our API references using [Doxygen](https://www.doxygen.nl/).
The following table shows some common documentation components and the syntax convention we
use for each:
<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
Adopt Microsoft CPP-Docs guidelines for
[Voice and Tone](https://github.com/MicrosoftDocs/cpp-docs/blob/main/styleguide/voice-tone.md).
We use the
[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
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 type, page layout, white space control, and other formatting
details are controlled via
[rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core). If you want to notify us
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
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 our documentation
## 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).
To learn how to build our documentation, refer to
[Building documentation](./docs/contribute/building.md).

20
README.md
View File

@@ -21,20 +21,20 @@ source software compilers, debuggers, and libraries. ROCm is fully integrated in
## 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.
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
cd docs

2
RELEASE.md
View File

@@ -11,7 +11,7 @@
<!-- 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 -->
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
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.
You can build our documentation via GitHub (in a pull request) or locally (using the command line or
Visual Studio (VS) Code.
## Pull request documentation builds
## GitHub
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.
If you open a pull request on the `develop` branch of a ROCm repository and scroll to the bottom of
the page, there is a summary panel. Next to the line
`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
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>/`.
![Screenshot of the GitHub documentation build link](../data/contribute/github-docs-build.png)
## 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
following commands from the project root:
Use the Python Virtual Environment (`venv`) and run 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.
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
test it locally using Visual Studio (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.
With the help of a few extensions, you can create a productive environment to author and test
documentation locally using Visual Studio (VS) Code. Follow these steps to configure VS Code:
### Configuring VS Code
1. Install the required extensions:
1. Install the following extensions:
* Python `(ms-python.python)`
* Live Server `(ritwickdey.LiveServer)`
* Python: `(ms-python.python)`
* Live Server: `(ritwickdey.LiveServer)`
2. Add the following entries in `.vscode/settings.json`
2. Add the following entries to `.vscode/settings.json`.
```json
{
"liveServer.settings.root": "/.vscode/build/html",
"liveServer.settings.wait": 1000,
"python.terminal.activateEnvInCurrentTerminal": true
}
{
"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.
* `liveServer.settings.wait`: Tells the live server to wait with the update in order to give Sphinx time to
regenerate the site contents and not refresh before the build is complete.
* `python.terminal.activateEnvInCurrentTerminal`: Activates the automatic virtual environment, so you
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
{
"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
},
{
"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
"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
}
],
"group": {
"kind": "build",
"isDefault": true
}
},
],
}
]
}
```
> (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
> 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`
* 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.)_
From the Command Palette, run `Python: Create Environment`. Select `venv` environment and
`docs/sphinx/requirements.txt`.
5. Build the docs
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.
Launch the default build task using one of the following options:
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
`.vscode/build/html/index.html` and select `Open with Live Server`. The
contents should update on every rebuild without having to refresh the
browser.
6. Open the live preview.
Navigate to the site output 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.

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