Update _toc.yml.in #2587

Rmalavally · 2023-12-06T19:59:01Z

DRAFT - TOC restructure

TOC restructure

docs/sphinx/_toc.yml.in

Changed title to caption

samjwu

The table of contents has a very specific format it accepts

A good example is the ROCm TOC: https://github.com/RadeonOpenCompute/ROCm/blob/develop/docs/sphinx/_toc.yml.in

docs/sphinx/_toc.yml.in

Corrected white space for - caption

Rmalavally

Thanks, Sam.

Fixed now

bghimireamd · 2023-12-07T16:23:02Z

LGTM

Rmalavally · 2023-12-07T16:24:33Z

LGTM

Thanks so much.

LisaDelaney · 2023-12-08T17:44:10Z

docs/sphinx/_toc.yml.in

-  - file: MIOpen_Porting_Guide
-  - file: apireference
- caption: About
+- caption: What is MIOpen?


this should not be a heading. it should be an intro page that describes the project.

We are still discussing the content for the Intro page. For now, we have reorganized the ToC on what's available and accurate. We have also removed the reference to release notes, as it is obsolete.

then we need to wait until we have a page to link to. It's confusing to have a heading represent a placeholder for a future page. A heading (='caption' in the toc) should only be there to represent pages that fit into that heading.

That's a decision we must make. Working with the team.

you can use the README file to get a little general info for a 'What is ..?' page until the team gets a chance to add to it. this page doesn't need to super long or elaborate, just has to describe what the project is/does.

Thanks, Lisa. Thanks so much for your help and comments.

LisaDelaney · 2023-12-08T17:47:11Z

docs/sphinx/_toc.yml.in

where is the API ref heading? you seem to have removed the entire former API ref section and there is no organization to the existing pages

https://github.com/ROCmSoftwarePlatform/MIOpen/blob/Rmalavally-patch-1/docs/sphinx/_toc.yml.in

look at the build--it's not rendering, so you need to fix the code.

Yep. It's a work in progress. Won't render yet.

you haven't added any of the Doxygen content (=the API ref)

file: reference/apireference.rst is what I have from them. Let's hold off until the structure is finalized.

Doxygen builds content automatically from the header files (which contains the code/text/content for the API). The team does does not supply the API textual content. This content is build into the "Doxygen" folder--this is what you need to include in the toc in order to incorporate the API ref.

LisaDelaney · 2023-12-08T18:06:00Z

these are no longer in the toc--is this intentional? Building MIOpen for Embedded Systems, Building the driver, Prerequisites

Rmalavally · 2023-12-08T18:15:25Z

these are no longer in the toc--is this intentional? Building MIOpen for Embedded Systems, Building the driver, Prerequisites

The restructure is based on their approval. I am not an expert to make this call. Let me finalize the content and get back to the team.

LisaDelaney · 2023-12-08T18:17:55Z

these are no longer in the toc--is this intentional? Building MIOpen for Embedded Systems, Building the driver, Prerequisites

The restructure is based on their approval. I am not an expert to make this call. Let me finalize the content and get back to the team.

We can't publish their documentation without the API ref. The API ref is the most important part.

Rmalavally · 2023-12-08T18:19:53Z

these are no longer in the toc--is this intentional? Building MIOpen for Embedded Systems, Building the driver, Prerequisites

The restructure is based on their approval. I am not an expert to make this call. Let me finalize the content and get back to the team.

We can't publish their documentation without the API ref. The API ref is the most important part.

Sure. I am aware. We used to have MIOpen on RTD before with other docs. Let's not rush without ensuring we are doing it correctly.

LisaDelaney · 2023-12-08T18:24:27Z

the landing page (index) is not ready. This PR needs more than toc edits before it can be merged...(at a minimum, add the updated index and what is pages)

Rmalavally · 2023-12-08T18:37:31Z

the landing page (index) is not ready. This PR needs more than toc edits before it can be merged...(at a minimum, add the updated index and what is pages)

I agree. Even with the minimum updates, it may not be consistent. Let's evaluate the implications of making this publicly available for this release.

Removed citation.rst based on customer request https://ontrack-internal.amd.com/browse/SWDEV-416591

samjwu · 2023-12-08T21:26:48Z

docs/sphinx/_toc.yml.in

+  - file: reference/driver.rst
+- caption: API reference
+  entries:
+  - file: reference/apireference.rst


the files here in the TOC are relative to the docs/ folder

for this to render correctly, apireference.rst needs to go into a folder named reference

same goes for tutorials

Updates

Folder for MIOpen reference

Rmalavally · 2023-12-12T15:28:46Z

@samjwu Using 'caption' breaks the build. Without the use of 'caption', it builds fine. Please advise.

JehandadKhan

Minor edits

JehandadKhan · 2023-12-12T15:59:11Z

docs/tutorials/what-is-MIOpen.rst

+.. meta::
+   :description: MIOpen is AMD’s deep learning primitives library, which provides highly optimized, and hand-tuned implementations of
+   different operators such as convolution, batch normalization, pooling, softmax, activation and layers for Recurrent Neural
+      Networks (RNNs), used in both training and inference [9].


Please remove the reference.

I did. Let me resend the PR. Here's the final text,

MIOpen is AMD’s deep learning primitives library, which provides highly optimized and hand-tuned implementations of different operators such as convolution, batch normalization, pooling, softmax, activation and layers for Recurrent Neural Networks (RNNs), used in both training and inference. Moreover, MIOpen is fully open source, including all its GPU kernels, complementing AMD’s open source ROCm stack. MIOpen is the first to extend the open source advantage into GPU vendor libraries thereby, continuing to embark on the same ethos as the deep learning community.

JehandadKhan · 2023-12-12T16:00:05Z

docs/tutorials/what-is-MIOpen.rst

+Networks (RNNs), used in both training and inference. Moreover, MIOpen is fully open-source including all its
+GPU kernels; complementing AMD’s open source ROCm stack [10]. MIOpen is the first to extend the open source
+advantage into GPU vendor libraries thereby, continuing to embark on the same ethos as the deep learning community.


Suggested change

Networks (RNNs), used in both training and inference. Moreover, MIOpen is fully open-source including all its

GPU kernels; complementing AMD’s open source ROCm stack [10]. MIOpen is the first to extend the open source

advantage into GPU vendor libraries thereby, continuing to embark on the same ethos as the deep learning community.

Networks (RNNs), used in both training and inference.

samjwu · 2023-12-12T16:04:23Z

@samjwu Using 'caption' breaks the build. Without the use of 'caption', it builds fine. Please advise.

Please refer to this version of the toc. It has the correct formatting to build the documentation

https://github.com/ROCm/MIOpen/blob/cac7a8872707c117d88cb56993470c7f371809cf/docs/sphinx/_toc.yml.in

Minor tweaks

Rmalavally · 2023-12-12T16:12:20Z

@samjwu Using 'caption' breaks the build. Without the use of 'caption', it builds fine. Please advise.

Please refer to this version of the toc. It has the correct formatting to build the documentation

https://github.com/ROCm/MIOpen/blob/cac7a8872707c117d88cb56993470c7f371809cf/docs/sphinx/_toc.yml.in

If I use hipSPARSElt as the template, then a title is required for each file. The updated ToC with titles builds fine as long as caption is not used.

https://github.com/ROCm/hipSPARSELt/blob/develop/docs/sphinx/_toc.yml.in

LisaDelaney · 2023-12-12T16:52:42Z

@samjwu Using 'caption' breaks the build. Without the use of 'caption', it builds fine. Please advise.

Please refer to this version of the toc. It has the correct formatting to build the documentation
https://github.com/ROCm/MIOpen/blob/cac7a8872707c117d88cb56993470c7f371809cf/docs/sphinx/_toc.yml.in

If I use hipSPARSElt as the template, then a title is required for each file. The updated ToC with titles builds fine as long as caption is not used.

https://github.com/ROCm/hipSPARSELt/blob/develop/docs/sphinx/_toc.yml.in

A title is not required...but I like to include it because, if you don't, it uses the title (H1) from within the file, which is often too long for a toc. You can find more info on correct syntax here: https://sphinx-external-toc.readthedocs.io/en/latest/user_guide/sphinx.html#basic-structure. Note that YAML is very particular about spacing/tabs.

LisaDelaney · 2023-12-12T16:57:01Z

docs/sphinx/_toc.yml.in

+- caption: API reference
+  subtrees:
+    - entries
+      - file: reference/apireference.rst


You're referencing a lot of files/folders that don't exit...and need to include the API ref from the doxygen folder (see my previous comment).

Bibek and I added the API ref from the Doxygen folder. @bghimireamd Please advise.

Exit? or Exist? We have reused all existing and original files. Sam recommended we create the appropriate folders, and as suggested, we used hipSPARSElt as the template. Should we remove the titles and keep it simple for 6.0?

that was a typo: I meant exist.

LisaDelaney · 2023-12-12T17:42:20Z

@Rmalavally I just noticed there is no gitignore file in this repo--can you create one (it will live in the root directory)? We don't need the build/doxygen folder/other build artifacts being tracked in the GitHub repo. You can use the ROCm repo gitignore as a reference.

Rmalavally · 2023-12-12T17:47:31Z

@Rmalavally I just noticed there is no gitignore file in this repo--can you create one (it will live in the root directory)? We don't need the build/doxygen folder/other build artifacts being tracked in the GitHub repo. You can use the ROCm repo gitignore as a reference.

Let me check. Could you also update the doc guidelines accordingly? For now, we have,

work on splitting up the individual files as needed (if applicable) and/or creating any new files you want (e.g. the "What is X?" page)
create any folders you need and put the appropriate files in the appropriate folders
get the toc file set up the way you want
update the index file(s) to align with the toc structure

Rmalavally · 2023-12-12T17:53:58Z

@Rmalavally I just noticed there is no gitignore file in this repo--can you create one (it will live in the root directory)? We don't need the build/doxygen folder/other build artifacts being tracked in the GitHub repo. You can use the ROCm repo gitignore as a reference.

Let me check. Could you also update the doc guidelines accordingly? For now, we have,

work on splitting up the individual files as needed (if applicable) and/or creating any new files you want (e.g. the "What is X?" page)
create any folders you need and put the appropriate files in the appropriate folders
get the toc file set up the way you want
update the index file(s) to align with the toc structure

The ROCm .gitignore file has _toc.yml. Assume we will have _toc.yml.in in the .gitignore file. Please confirm.

LisaDelaney · 2023-12-12T18:13:40Z

@Rmalavally I just noticed there is no gitignore file in this repo--can you create one (it will live in the root directory)? We don't need the build/doxygen folder/other build artifacts being tracked in the GitHub repo. You can use the ROCm repo gitignore as a reference.

Let me check. Could you also update the doc guidelines accordingly? For now, we have,

work on splitting up the individual files as needed (if applicable) and/or creating any new files you want (e.g. the "What is X?" page)
create any folders you need and put the appropriate files in the appropriate folders
get the toc file set up the way you want
update the index file(s) to align with the toc structure

The ROCm .gitignore file has _toc.yml. Assume we will have _toc.yml.in in the .gitignore file. Please confirm.

No, _toc.yml is an autogenerated file (a copy of _toc.yml.in); _toc.yml.in should not be in the gitignore file.

Rmalavally · 2023-12-12T18:14:56Z

@Rmalavally I just noticed there is no gitignore file in this repo--can you create one (it will live in the root directory)? We don't need the build/doxygen folder/other build artifacts being tracked in the GitHub repo. You can use the ROCm repo gitignore as a reference.

Let me check. Could you also update the doc guidelines accordingly? For now, we have,

work on splitting up the individual files as needed (if applicable) and/or creating any new files you want (e.g. the "What is X?" page)
create any folders you need and put the appropriate files in the appropriate folders
get the toc file set up the way you want
update the index file(s) to align with the toc structure

The ROCm .gitignore file has _toc.yml. Assume we will have _toc.yml.in in the .gitignore file. Please confirm.

No, _toc.yml is an autogenerated file (a copy of _toc.yml.in); _toc.yml.in should not be in the gitignore file.

Ok. Good to know. Thanks for clarifying.

junliume · 2023-12-30T19:35:36Z

@Rmalavally this PR is still in draft state, if we are pursuing it to merging, please update it and resolve all the conflicts above. Thanks!

…avally-patch-1

LisaDelaney · 2024-01-19T17:34:15Z

.readthedocs.yaml


 python:
   install:
   - requirements: docs/sphinx/requirements.txt

 build:
-   os: ubuntu-22.04


@samjwu is this change correct?

samjwu

.readthedocs.yaml should not need to be changed. It is for the ReadtheDocs site build configurations

Update _toc.yml.in

6d2ae15

TOC restructure

samjwu reviewed Dec 6, 2023

View reviewed changes

docs/sphinx/_toc.yml.in Outdated Show resolved Hide resolved

Rmalavally added 2 commits December 6, 2023 12:10

Update _toc.yml.in

856b2f1

Changed title to caption

Update _toc.yml.in

cae46fd

samjwu previously requested changes Dec 6, 2023

View reviewed changes

samjwu reviewed Dec 6, 2023

View reviewed changes

docs/sphinx/_toc.yml.in Outdated Show resolved Hide resolved

samjwu reviewed Dec 6, 2023

View reviewed changes

docs/sphinx/_toc.yml.in Outdated Show resolved Hide resolved

Rmalavally and others added 3 commits December 6, 2023 12:21

Update _toc.yml.in

709164f

Corrected white space for - caption

Update _toc.yml.in

0832e53

Update _toc.yml.in

cac7a88

samjwu added the documentation label Dec 6, 2023

Rmalavally commented Dec 6, 2023

View reviewed changes

saadrahim marked this pull request as draft December 6, 2023 22:35

Rmalavally marked this pull request as ready for review December 7, 2023 16:24

LisaDelaney reviewed Dec 8, 2023

View reviewed changes

LisaDelaney marked this pull request as draft December 8, 2023 17:55

Update _toc.yml.in

79970e0

Removed citation.rst based on customer request https://ontrack-internal.amd.com/browse/SWDEV-416591

samjwu reviewed Dec 8, 2023

View reviewed changes

Rmalavally added 2 commits December 11, 2023 17:57

Update _toc.yml.in

f7a771b

Updates

Create reference

3c5e83c

Folder for MIOpen reference

Update _toc.yml.in

6af3b71

Update what-is-MIOpen.rst

64d6b3a

JehandadKhan requested changes Dec 12, 2023

View reviewed changes

Rmalavally added 2 commits December 12, 2023 08:05

Update what-is-MIOpen.rst

e75956f

Update what-is-MIOpen.rst

e79fa33

Minor tweaks

LisaDelaney reviewed Dec 12, 2023

View reviewed changes

bghimireamd mentioned this pull request Jan 4, 2024

add_gitignore : adding .gitignore file #2611

Closed

bghimireamd added 9 commits January 18, 2024 23:00

Rmalavally-patch-1 : edit index.rst file and added install.rst

054b3d1

Rmalavally-patch-1 : fix code block in install.rst

d3cc79b

Rmalavally-patch-1 : fix install.rst

bd1c96d

Rmalavally-patch-1 : fix install.rst

880be0b

Rmalavally-patch-1 : render code section in install.rst

4eb7f47

Rmalavally-patch-1 : render all code section in install.rst

888eb7c

Rmalavally-patch-1 : render all code section in install.rst

286b8d7

Rmalavally-patch-1: fix referencing multiple docs

6517398

Merge branch 'Rmalavally-patch-1' of github.com:ROCm/MIOpen into Rmal…

1376bdb

…avally-patch-1

LisaDelaney reviewed Jan 19, 2024

View reviewed changes

samjwu requested changes Jan 19, 2024

View reviewed changes

LisaDelaney closed this Mar 4, 2024

junliume deleted the Rmalavally-patch-1 branch June 25, 2024 05:08

Update _toc.yml.in #2587

Update _toc.yml.in #2587

Conversation

Rmalavally commented Dec 6, 2023 • edited Loading

samjwu left a comment

Choose a reason for hiding this comment

Rmalavally left a comment

Choose a reason for hiding this comment

bghimireamd commented Dec 7, 2023

Rmalavally commented Dec 7, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LisaDelaney Dec 8, 2023 • edited Loading

Choose a reason for hiding this comment

LisaDelaney commented Dec 8, 2023

Rmalavally commented Dec 8, 2023

LisaDelaney commented Dec 8, 2023

Rmalavally commented Dec 8, 2023

LisaDelaney commented Dec 8, 2023

Rmalavally commented Dec 8, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Rmalavally commented Dec 12, 2023

JehandadKhan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samjwu commented Dec 12, 2023

Rmalavally commented Dec 12, 2023 • edited Loading

LisaDelaney commented Dec 12, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LisaDelaney commented Dec 12, 2023

Rmalavally commented Dec 12, 2023

Rmalavally commented Dec 12, 2023

LisaDelaney commented Dec 12, 2023

Rmalavally commented Dec 12, 2023

junliume commented Dec 30, 2023

Choose a reason for hiding this comment

samjwu left a comment

Choose a reason for hiding this comment

Rmalavally commented Dec 6, 2023 •

edited

Loading

LisaDelaney Dec 8, 2023 •

edited

Loading

Rmalavally commented Dec 12, 2023 •

edited

Loading