From 14153b95400dc7a2401de47bd55cb51953369a68 Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Wed, 9 Aug 2023 14:02:05 -0600 Subject: [PATCH] fix typos and add links to rocm-docs-core user and developer guides in contributing section (#2372) --- CONTRIBUTING.md | 31 +++++++++---------------------- docs/about.md | 2 ++ docs/contribute/feedback.md | 2 +- 3 files changed, 12 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5344dbafa..c5e65aa28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,15 +13,19 @@ 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 +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 +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 @@ -35,33 +39,16 @@ as follows: 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 snake case (all lower case letters and underscores instead of spaces) for file names. For example, `example_file_name.md`. -Our documentation follows pitchfork for folder structure. +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 -place in the /docs/data folder. - -## How to provide feedback for ROCm documentation - -There are three standard ways to provide feedback for this repository. - -### Pull Request - -All contributions to ROCm documentation should arrive via the -[GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) -targetting the develop branch of the repository. If you are unable to contribute -via the GitHub Flow, feel free to email us. TODO, confirm email address. - -### GitHub Issue - -Issues on existing or absent docs can be filed as [GitHub issues -](https://github.com/RadeonOpenCompute/ROCm/issues). - -### Email Feedback +placed in the `/docs/data` folder. ## Language and Style diff --git a/docs/about.md b/docs/about.md index b14b1e6c1..12d8fd6df 100644 --- a/docs/about.md +++ b/docs/about.md @@ -12,6 +12,8 @@ project that applies customization for our documentation. This project is the tool most ROCm repositories use as part of the documentation build. It is also available as a [pip package on PyPI](https://pypi.org/project/rocm-docs-core/). +See the user and developer guides for rocm-docs-core at {doc}`rocm-docs-core documentation `. + ## Sphinx [Sphinx](https://www.sphinx-doc.org/en/master/) is a documentation generator diff --git a/docs/contribute/feedback.md b/docs/contribute/feedback.md index fcf8db9b9..573fd6fa6 100644 --- a/docs/contribute/feedback.md +++ b/docs/contribute/feedback.md @@ -1,4 +1,4 @@ -# How to provide feedback for for ROCm documentation +# How to provide feedback for ROCm documentation There are four standard ways to provide feedback for this repository.