mirror of
https://github.com/ROCm/ROCm.git
synced 2026-01-10 07:08:08 -05:00
Merge branch 'develop' into docs/6.0.0
This commit is contained in:
76
.github/ISSUE_TEMPLATE/0_issue_report.yml
vendored
76
.github/ISSUE_TEMPLATE/0_issue_report.yml
vendored
@@ -1,76 +0,0 @@
|
||||
name: Issue Report
|
||||
description: File a report for something not working correctly.
|
||||
title: "[Issue]: "
|
||||
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thank you for taking the time to fill out this report!
|
||||
|
||||
On a Linux system, you can acquire your OS, CPU, GPU, and ROCm version (for filling out this report) with the following commands:
|
||||
echo "OS:" && cat /etc/os-release | grep -E "^(NAME=|VERSION=)";
|
||||
echo "CPU: " && cat /proc/cpuinfo | grep "model name" | sort --unique;
|
||||
echo "GPU:" && /opt/rocm/bin/rocminfo | grep -E "^\s*(Name|Marketing Name)";
|
||||
echo "ROCm in /opt:" && ls -1 /opt | grep -E "rocm-";
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Problem Description
|
||||
description: Describe the issue you encountered.
|
||||
placeholder: "The steps to reproduce can be included here, or in the dedicated section further below."
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
attributes:
|
||||
label: Operating System
|
||||
description: What is the name and version number of the OS?
|
||||
placeholder: "e.g. Ubuntu 22.04.3 LTS (Jammy Jellyfish)"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
attributes:
|
||||
label: CPU
|
||||
description: What CPU did you encounter the issue on?
|
||||
placeholder: "e.g. AMD Ryzen 9 5900HX with Radeon Graphics"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
attributes:
|
||||
label: GPU
|
||||
description: What GPU(s) did you encounter the issue on?
|
||||
placeholder: "e.g. MI200"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
attributes:
|
||||
label: ROCm Version
|
||||
description: What version(s) of ROCm did you encounter the issue on?
|
||||
placeholder: "e.g. 5.7.0"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
attributes:
|
||||
label: ROCm Component
|
||||
description: (Optional) If this issue relates to a specific ROCm component, it can be mentioned here.
|
||||
placeholder: "e.g. rocBLAS"
|
||||
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Steps to Reproduce
|
||||
description: (Optional) Detailed steps to reproduce the issue.
|
||||
placeholder: Please also include what you expected to happen, and what actually did, at the failing step(s).
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Output of /opt/rocm/bin/rocminfo --support
|
||||
description: The output of rocminfo --support will help to better address the problem.
|
||||
placeholder: |
|
||||
ROCk module is loaded
|
||||
=====================
|
||||
HSA System Attributes
|
||||
=====================
|
||||
[...]
|
||||
validations:
|
||||
required: true
|
||||
160
.github/ISSUE_TEMPLATE/issue_report.yml
vendored
160
.github/ISSUE_TEMPLATE/issue_report.yml
vendored
@@ -45,6 +45,9 @@ body:
|
||||
description: What GPU(s) did you encounter the issue on (you can select multiple GPUs from the list)
|
||||
multiple: true
|
||||
options:
|
||||
- AMD Instinct MI300
|
||||
- AMD Instinct MI300A
|
||||
- AMD Instinct MI300X
|
||||
- AMD Instinct MI250X
|
||||
- AMD Instinct MI250
|
||||
- AMD Instinct MI210
|
||||
@@ -85,6 +88,7 @@ body:
|
||||
description: What version(s) of ROCm did you encounter the issue on?
|
||||
multiple: true
|
||||
options:
|
||||
- ROCm 6.0.0
|
||||
- ROCm 5.7.1
|
||||
- ROCm 5.7.0
|
||||
- ROCm 5.6.0
|
||||
@@ -96,104 +100,63 @@ body:
|
||||
attributes:
|
||||
label: ROCm Component
|
||||
description: (Optional) If this issue relates to a specific ROCm component, it can be mentioned here.
|
||||
multiple: true
|
||||
options:
|
||||
- Other
|
||||
- AMD Common Language Runtime
|
||||
- AMD MIGraphX
|
||||
- AMD System Management Interface
|
||||
- amdgpu KCL/autoconf
|
||||
- amdgpu Kernel-mode GPU Driver
|
||||
- amdgpu-install
|
||||
- AOMP
|
||||
- AOMP Extras
|
||||
- AqlProfile
|
||||
- build-infra
|
||||
- chelsio
|
||||
- clang-ocl
|
||||
- Composable Kernel
|
||||
- dkms
|
||||
- docker / ROCm-docker
|
||||
- flang
|
||||
- gpuburn
|
||||
- half
|
||||
- HIP
|
||||
- HIP Examples
|
||||
- hipBLAS
|
||||
- hipBLASLt
|
||||
- HIPCC
|
||||
- hipCUB
|
||||
- hip-examples-private
|
||||
- hipFFT
|
||||
- hipfort
|
||||
- HIPIFY
|
||||
- hipRAND
|
||||
- hipSOLVER
|
||||
- hipSPARSE
|
||||
- hipSPARSELt
|
||||
- hipTensor
|
||||
- hip-tests
|
||||
- HSA Runtime
|
||||
- infrastructure
|
||||
- jenkins-utils
|
||||
- libdrm
|
||||
- Linux BPI packaging framework
|
||||
- llvm-project
|
||||
- Mesa
|
||||
- meta
|
||||
- MIOpen
|
||||
- MIVisionX
|
||||
- ml-framework-ci
|
||||
- MLSEQA_TestRepo
|
||||
- OpenCL API C++ Bindings
|
||||
- OpenCL API Headers
|
||||
- OpenCL Conformance Test Suite
|
||||
- OpenCL ICD Loader
|
||||
- perftest-p2p
|
||||
- prototype
|
||||
- RCCL
|
||||
- rccl-rdma-sharp-plugins
|
||||
- rocALUTION
|
||||
- rocBLAS
|
||||
- ROCdbgapi
|
||||
- ROCdebug-agent
|
||||
- rocFFT
|
||||
- ROCgdb
|
||||
- ROCK
|
||||
- ROCm Documentation/Website
|
||||
- ROCm Data Center Tool
|
||||
- ROCm Examples
|
||||
- ROCm for Windows
|
||||
- ROCm Performance Primitives
|
||||
- ROCm System Management Interface Library
|
||||
- ROCm Thrust
|
||||
- ROCm Validation Suite
|
||||
- rocm_bandwidth_test
|
||||
- rocm-cmake
|
||||
- rocm-core
|
||||
- rocm-docs-core
|
||||
- rocminfo
|
||||
- rocMLIR
|
||||
- rocmtools
|
||||
- rocPRIM
|
||||
- rocprofiler
|
||||
- rocRAND
|
||||
- ROCR-Runtime
|
||||
- rocSOLVER
|
||||
- rocSPARSE
|
||||
- roctracer
|
||||
- ROCT-Thunk-Interface
|
||||
- rocWMMA
|
||||
- Tensile
|
||||
- umr
|
||||
- ibv_rc_pingpong-amd
|
||||
- mellanox
|
||||
- mpitest
|
||||
- Pytorch
|
||||
- Tensorflow
|
||||
- APEX
|
||||
- torchvision
|
||||
- Magma
|
||||
- Other
|
||||
- AMDMIGraphX
|
||||
- amdsmi
|
||||
- aomp
|
||||
- aomp-extras
|
||||
- clang-ocl
|
||||
- clr
|
||||
- composable_kernel
|
||||
- flang
|
||||
- half
|
||||
- HIP
|
||||
- hipBLAS
|
||||
- HIPCC
|
||||
- hipCUB
|
||||
- HIP-Examples
|
||||
- hipFFT
|
||||
- hipfort
|
||||
- HIPIFY
|
||||
- hipSOLVER
|
||||
- hipSPARSE
|
||||
- hipTensor
|
||||
- llvm-project
|
||||
- MIOpen
|
||||
- MIVisionX
|
||||
- rccl
|
||||
- rdc
|
||||
- rocALUTION
|
||||
- rocBLAS
|
||||
- ROCdbgapi
|
||||
- rocFFT
|
||||
- ROCgdb
|
||||
- ROCK-Kernel-Driver
|
||||
- ROCm
|
||||
- rocm_bandwidth_test
|
||||
- rocm_smi_lib
|
||||
- rocm-cmake
|
||||
- ROCm-CompilerSupport
|
||||
- rocm-core
|
||||
- ROCm-Device-Libs
|
||||
- rocminfo
|
||||
- rocMLIR
|
||||
- ROCmValidationSuite
|
||||
- rocPRIM
|
||||
- rocprofiler
|
||||
- rocr_debug_agent
|
||||
- rocRAND
|
||||
- ROCR-Runtime
|
||||
- rocSOLVER
|
||||
- rocSPARSE
|
||||
- rocThrust
|
||||
- roctracer
|
||||
- ROCT-Thunk-Interface
|
||||
- rocWMMA
|
||||
- rpp
|
||||
- Tensile
|
||||
default: 32
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Steps to Reproduce
|
||||
@@ -213,4 +176,5 @@ body:
|
||||
label: Additional Information
|
||||
description: (Optional) Any additional information that is relevant, e.g. relevant environment variables, dockerfiles, log files, dmesg output (on Linux), etc.
|
||||
validations:
|
||||
required: false
|
||||
required: false
|
||||
|
||||
@@ -24,7 +24,7 @@ cmake_minimum_required(VERSION 3.18.0)
|
||||
|
||||
project(ROCm VERSION 5.7.1 LANGUAGES NONE)
|
||||
|
||||
option(ROCM_BUILD_DOCS "Build ROCm documentation" ON)
|
||||
option(BUILD_DOCS "Build ROCm documentation" ON)
|
||||
|
||||
include(GNUInstallDirs)
|
||||
|
||||
@@ -35,6 +35,6 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules")
|
||||
include(Dependencies)
|
||||
|
||||
# Build docs
|
||||
if(ROCM_BUILD_DOCS)
|
||||
if(BUILD_DOCS)
|
||||
add_subdirectory(docs)
|
||||
endif()
|
||||
|
||||
278
CONTRIBUTING.md
278
CONTRIBUTING.md
@@ -1,229 +1,95 @@
|
||||
# Contributing to ROCm documentation
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="description" content="Contributing to ROCm">
|
||||
<meta name="keywords" content="ROCm, contributing, contribute, maintainer, contributor">
|
||||
</head>
|
||||
|
||||
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.
|
||||
# Contribute to ROCm
|
||||
|
||||
If you have issues when trying to contribute, refer to the
|
||||
[discussions](https://github.com/RadeonOpenCompute/ROCm/discussions) page in our GitHub
|
||||
repository.
|
||||
AMD values and encourages contributions to our code and documentation. If you want to contribute
|
||||
to our ROCm repositories, first review the following guidance. For documentation-specific information,
|
||||
see [Contributing to ROCm docs](./docs/contribute/contribute-docs.md).
|
||||
|
||||
## Folder structure and naming convention
|
||||
ROCm is a software stack made up of a collection of drivers, development tools, and APIs that enable
|
||||
GPU programming from low-level kernel to end-user applications. 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)), these use
|
||||
project-specific contribution guidelines and workflow. Refer to their repositories for more information.
|
||||
All other ROCm components follow the workflow described in the following sections.
|
||||
|
||||
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.
|
||||
## Development workflow
|
||||
|
||||
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 uses GitHub to host code, collaborate, and manage version control. We use pull requests (PRs)
|
||||
for all changes within our repositories. We use
|
||||
[GitHub issues](https://github.com/ROCm/ROCm/issues) to track known issues, such as
|
||||
bugs.
|
||||
|
||||
Our naming structure uses kebab case; for example, `my-file-name.rst`.
|
||||
### Issue tracking
|
||||
|
||||
## Supported formats and syntax
|
||||
Before filing a new issue, search the
|
||||
[existing issues](https://github.com/ROCm/ROCm/issues) to make sure your issue isn't
|
||||
already listed.
|
||||
|
||||
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.
|
||||
General issue guidelines:
|
||||
|
||||
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/).
|
||||
* 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.
|
||||
|
||||
The following table shows some common documentation components and the syntax convention we
|
||||
use for each:
|
||||
### Pull requests
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Component</th>
|
||||
<th>RST syntax</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Code blocks</td>
|
||||
<td>
|
||||
Our repositories typically use the **develop** branch an integration branch for new code so, when
|
||||
making a PR, target this branch.
|
||||
|
||||
```rst
|
||||
|
||||
.. code-block:: language-name
|
||||
|
||||
My code block.
|
||||
When creating a PR, use the following process. Note that each repository may include additional,
|
||||
project-specific steps. Refer to each repository's PR process for any additional steps.
|
||||
|
||||
* Identify the issue you want to fix
|
||||
* Target the **develop** branch for integration
|
||||
* Ensure your code builds successfully
|
||||
* Each component has a suite of test cases to run; include the log of the successful test run in your PR
|
||||
* Do not break existing test cases
|
||||
* New functionality is only merged with new unit tests
|
||||
* If your PR includes a new feature, you must provide an application or test so we can ensure that the
|
||||
feature works and continues to be valid in the future
|
||||
* Tests must have good code coverage
|
||||
* Submit your PR and work with the reviewer or maintainer to get your PR approved
|
||||
* Once approved, the PR is brought onto internal CI systems and may be merged into the component
|
||||
during our release cycle, as coordinated by the maintainer
|
||||
* We'll inform you once your change is committed
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Cross-referencing internal files</td>
|
||||
<td>
|
||||
You can look up each license on the [ROCm licensing](./docs/about/licensing.md) page.
|
||||
|
||||
```rst
|
||||
### New feature development
|
||||
|
||||
:doc:`Title <../path/to/file/filename>`
|
||||
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.
|
||||
|
||||
```
|
||||
### Documentation
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>External links</td>
|
||||
<td>
|
||||
Submit ROCm documentation changes to our
|
||||
[documentation repository](https://github.com/ROCm/ROCm). You must update
|
||||
documentation related to any new feature or API contribution.
|
||||
|
||||
```rst
|
||||
Note that each ROCm project uses its own repository for documentation.
|
||||
|
||||
`link name <URL>`_
|
||||
## Future development workflow
|
||||
|
||||
```
|
||||
|
||||
</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
|
||||
|
||||
We use the
|
||||
[Google developer documentation style guide](https://developers.google.com/style/highlights) to
|
||||
guide our content.
|
||||
|
||||
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.
|
||||
|
||||
## Building our documentation
|
||||
|
||||
<!-- % TODO: Fix the link to be able to work at every files -->
|
||||
To learn how to build our documentation, refer to
|
||||
[Building documentation](./building.md).
|
||||
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.
|
||||
|
||||
60
GOVERNANCE.md
Normal file
60
GOVERNANCE.md
Normal file
@@ -0,0 +1,60 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="description" content="ROCm governance model">
|
||||
<meta name="keywords" content="ROCm, governance">
|
||||
</head>
|
||||
|
||||
# Governance model
|
||||
|
||||
ROCm is a software stack made up of a collection of drivers, development tools, and APIs that enable
|
||||
GPU programming from the low-level kernel to end-user applications.
|
||||
|
||||
Components of ROCm that are inherited from external projects (such as
|
||||
[LLVM](https://github.com/ROCm/llvm-project) and
|
||||
[Kernel driver](https://github.com/ROCm/ROCK-Kernel-Driver)) follow their own
|
||||
governance model and code of conduct. All other components of ROCm are governed by this
|
||||
document.
|
||||
|
||||
## Governance
|
||||
|
||||
ROCm is led and managed by AMD.
|
||||
|
||||
We welcome contributions from the community. Our maintainers review all proposed changes to
|
||||
ROCm.
|
||||
|
||||
## Roles
|
||||
|
||||
* **Maintainers** are responsible for their designated component and repositories.
|
||||
* **Contributors** provide input and suggest changes to existing components.
|
||||
|
||||
### Maintainers
|
||||
|
||||
Maintainers are appointed by AMD. They are able to approve changes and can commit to our
|
||||
repositories. They must use pull requests (PRs) for all changes.
|
||||
|
||||
You can find the list of maintainers in the CODEOWNERS file of each repository. Code owners differ
|
||||
between repositories.
|
||||
|
||||
### Contributors
|
||||
|
||||
If you're not a maintainer, you're a contributor. We encourage the ROCm community to contribute in
|
||||
several ways:
|
||||
|
||||
* Help other community members by posting questions or solutions on our
|
||||
[GitHub discussion forums](https://github.com/ROCm/ROCm/discussions)
|
||||
* Notify us of a bugs by filing an issue report on
|
||||
[GitHub Issues](https://github.com/ROCm/ROCm/issues)
|
||||
* Improve our documentation by submitting a PR to our
|
||||
[repository](https://github.com/ROCm/ROCm/)
|
||||
* Improve the code base (for smaller or contained changes) by submitting a PR to the component
|
||||
* Suggest larger features by adding to the *Ideas* category in the
|
||||
[GitHub discussion forum](https://github.com/ROCm/ROCm/discussions)
|
||||
|
||||
For more information, refer to our [contribution guidelines](CONTRIBUTING.md).
|
||||
|
||||
## Code of conduct
|
||||
|
||||
To engage with any AMD ROCm component that is hosted on GitHub, you must abide by the
|
||||
[GitHub community guidelines](https://docs.github.com/en/site-policy/github-terms/github-community-guidelines)
|
||||
and the
|
||||
[GitHub community code of conduct](https://docs.github.com/en/site-policy/github-terms/github-community-code-of-conduct).
|
||||
@@ -26,7 +26,7 @@
|
||||
|
||||
include(FetchContent)
|
||||
|
||||
if(ROCM_BUILD_DOCS)
|
||||
if(BUILD_DOCS)
|
||||
find_package(ROCM 0.11.0 CONFIG QUIET PATHS "${ROCM_PATH}") # First version with Sphinx doc gen improvement
|
||||
if(NOT ROCM_FOUND)
|
||||
message(STATUS "ROCm CMake not found. Fetching...")
|
||||
@@ -44,58 +44,4 @@ if(ROCM_BUILD_DOCS)
|
||||
else()
|
||||
find_package(ROCM 0.11.0 CONFIG REQUIRED PATHS "${ROCM_PATH}")
|
||||
endif()
|
||||
|
||||
if(Python_FIND_VIRTUALENV STREQUAL "ONLY" AND NOT DEFINED ENV{VIRTUAL_ENV})
|
||||
if(NOT EXISTS "${CMAKE_CURRENT_BINARY_DIR}/.venv")
|
||||
message(STATUS "Python virtualenv use requested but not found. Fetching...")
|
||||
find_program(BOOTSTRAP_PYTHON_EXE python3 REQUIRED)
|
||||
execute_process(
|
||||
COMMAND "${BOOTSTRAP_PYTHON_EXE}" -m pip install --user virtualenv
|
||||
OUTPUT_QUIET
|
||||
COMMAND_ERROR_IS_FATAL ANY
|
||||
)
|
||||
execute_process(
|
||||
COMMAND "${BOOTSTRAP_PYTHON_EXE}" -m virtualenv "${CMAKE_CURRENT_BINARY_DIR}/.venv"
|
||||
OUTPUT_QUIET
|
||||
COMMAND_ERROR_IS_FATAL ANY
|
||||
)
|
||||
endif()
|
||||
set(ENV{VIRTUAL_ENV} "${CMAKE_CURRENT_BINARY_DIR}/.venv")
|
||||
|
||||
if(WIN32)
|
||||
set(ENV{PATH} "${CMAKE_CURRENT_BINARY_DIR}/.venv/Scripts;$ENV{PATH}")
|
||||
else()
|
||||
set(ENV{PATH} "${CMAKE_CURRENT_BINARY_DIR}/.venv/bin:$ENV{PATH}")
|
||||
endif()
|
||||
|
||||
find_package(Python REQUIRED)
|
||||
|
||||
# TODO: shortcircuit if installed
|
||||
execute_process(
|
||||
COMMAND "${Python_EXECUTABLE}" -m pip install pip-tools
|
||||
OUTPUT_QUIET
|
||||
COMMAND_ERROR_IS_FATAL ANY
|
||||
)
|
||||
|
||||
list(APPEND CMAKE_CONFIGURE_DEPENDS "${PROJECT_SOURCE_DIR}/docs/sphinx/requirements.in")
|
||||
file(MAKE_DIRECTORY "$ENV{VIRTUAL_ENV}/usr/share/${PROJECT_NAME}")
|
||||
if("${PROJECT_SOURCE_DIR}/docs/sphinx/requirements.in" IS_NEWER_THAN "$ENV{VIRTUAL_ENV}/usr/share/${PROJECT_NAME}/requirements.txt")
|
||||
execute_process(
|
||||
COMMAND "${Python_EXECUTABLE}" -m piptools compile
|
||||
"${PROJECT_SOURCE_DIR}/docs/sphinx/requirements.in"
|
||||
--output-file
|
||||
"$ENV{VIRTUAL_ENV}/usr/share/${PROJECT_NAME}/requirements.txt"
|
||||
OUTPUT_QUIET
|
||||
ERROR_QUIET
|
||||
COMMAND_ERROR_IS_FATAL ANY
|
||||
)
|
||||
execute_process(
|
||||
COMMAND "${Python_EXECUTABLE}" -m piptools sync
|
||||
"$ENV{VIRTUAL_ENV}/usr/share/${PROJECT_NAME}/requirements.txt"
|
||||
OUTPUT_QUIET
|
||||
ERROR_QUIET
|
||||
COMMAND_ERROR_IS_FATAL ANY
|
||||
)
|
||||
endif()
|
||||
endif()
|
||||
endif()
|
||||
|
||||
229
docs/contribute/contribute-docs.md
Normal file
229
docs/contribute/contribute-docs.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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
|
||||
|
||||
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.
|
||||
|
||||
All images are stored in the `/docs/data` folder. An image's file path mirrors that of the documentation
|
||||
file where it is used.
|
||||
|
||||
Our naming structure uses kebab case; for example, `my-file-name.rst`.
|
||||
|
||||
## Supported formats and syntax
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
We use the
|
||||
[Google developer documentation style guide](https://developers.google.com/style/highlights) to
|
||||
guide our content.
|
||||
|
||||
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.
|
||||
|
||||
## Building our documentation
|
||||
|
||||
<!-- % TODO: Fix the link to be able to work at every files -->
|
||||
To learn how to build our documentation, refer to
|
||||
[Building documentation](./building.md).
|
||||
@@ -7,8 +7,7 @@ root: index
|
||||
subtrees:
|
||||
- entries:
|
||||
- file: what-is-rocm.md
|
||||
- file: about/release-notes.md
|
||||
title: Release notes
|
||||
- file: about/whats-new/whats-new.md
|
||||
subtrees:
|
||||
- entries:
|
||||
- file: about/CHANGELOG.md
|
||||
@@ -85,7 +84,7 @@ subtrees:
|
||||
- file: conceptual/compiler-disambiguation.md
|
||||
title: Compiler disambiguation
|
||||
- file: about/compatibility/openmp.md
|
||||
title: OpenMP
|
||||
title: OpenMP
|
||||
- file: conceptual/file-reorg.md
|
||||
title: File structure (Linux FHS)
|
||||
- file: conceptual/gpu-isolation.md
|
||||
@@ -104,15 +103,19 @@ subtrees:
|
||||
- caption: Contribute
|
||||
entries:
|
||||
- file: contribute/index.md
|
||||
title: Contribute to ROCm docs
|
||||
title: Contribute to ROCm
|
||||
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/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: about/license.md
|
||||
title: ROCm license
|
||||
|
||||
|
||||
Reference in New Issue
Block a user