diff --git a/.wordlist.txt b/.wordlist.txt index b08c9a768..a586907b0 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -46,6 +46,7 @@ cd CDNA CentOS centric +changelog chiplet CIFAR CLI @@ -361,6 +362,7 @@ repos Req req resampling +RST reStructuredText RHEL Rickle diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23d616d3b..36af88949 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 `. +## 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 ` 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentRST syntax
Code blocks + +```rst + +.. code-block:: language-name + + My code block. + + +``` + +
Cross-referencing internal files + +```rst + +:doc:`Title <../path/to/file/filename>` + +``` + +
External links + +```rst + +`link name `_ + +``` + +
Headings + +```rst + +****************** +Chapter title (H1) +****************** + +Section title (H2) +=============== + +Subsection title (H3) +--------------------- + +Sub-subsection title (H4) +^^^^^^^^^^^^^^^^^^^^ + + +``` + +
Images + +```rst + +.. image:: image1.png + +``` + +
Internal links + +```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`. + +``` + +
Lists + +```rst + +# Ordered (numbered) list item + +* Unordered (bulleted) list item + +``` + +
Math (block) + +```rst + +.. math:: + + A = \begin{pmatrix} + 0.0 & 1.0 & 1.0 & 3.0 \\ + 4.0 & 5.0 & 6.0 & 7.0 \\ + \end{pmatrix} + +``` + +
Math (inline) + +```rst + +:math:`2 \times 2 ` + +``` + +
Notes + +```rst + +.. note:: + + My note here. + +``` + +
Tables + +```rst + +.. csv-table:: Optional title here + :widths: 30, 70 #optional column widths + :header: "entry1 header", "entry2 header" + + "entry1", "entry2" + +``` + +
## 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). diff --git a/README.md b/README.md index 44e86b270..3c8c7661c 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/RELEASE.md b/RELEASE.md index 6326824d3..b8d378fcb 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -11,7 +11,7 @@ -The release notes for the ROCm platform. +Welcome to the release notes for the ROCm platform. ------------------- diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 6326824d3..b8d378fcb 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -11,7 +11,7 @@ -The release notes for the ROCm platform. +Welcome to the release notes for the ROCm platform. ------------------- diff --git a/docs/contribute/building.md b/docs/contribute/building.md index eb04ce8f6..1228ae438 100644 --- a/docs/contribute/building.md +++ b/docs/contribute/building.md @@ -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/`) 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//` - * 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--.com.readthedocs.build/projects/alpha/en//`. +![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. diff --git a/docs/contribute/index.md b/docs/contribute/index.md deleted file mode 100644 index 23d616d3b..000000000 --- a/docs/contribute/index.md +++ /dev/null @@ -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 `. - -## 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 ` 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). diff --git a/docs/data/contribute/github-docs-build.png b/docs/data/contribute/github-docs-build.png new file mode 100644 index 000000000..44149b83b Binary files /dev/null and b/docs/data/contribute/github-docs-build.png differ