Documentation Refactor

docs/.sphinx/_toc.yml.in

@@ -1,26 +1,35 @@
 root: index
 subtrees:
-- caption: User Guide
+- caption: User Reference
+  entries:
+    - file: .doxygen/docBin/html/index
+    - file: reference/kernel_language
+    - file: reference/math_api
+    - file: reference/glossary
+    - file: reference/deprecated_api_list
+- caption: User How to Guides
+  entries:
+    - file: how_to_guides/install.md
+- caption: User Tutorials
+  entries:
+    - file: tutorials/saxpy.md
+- caption: Developer How to Guides
+  entries:
+    - file: developer_guide/build
+- caption: Legacy Reference
+  entries:
+    - file: reference/terms
+- caption: Legacy User Guide
   entries:
     - file: user_guide/programming_manual
     - file: user_guide/hip_rtc
     - file: user_guide/faq
+- caption: Legacy How to Guides
+  entries:
+    - file: how_to_guides/debugging.md
     - file: user_guide/hip_porting_guide
     - file: user_guide/hip_porting_driver_api
-- caption: How to Guides
-  entries:
-  - file: how_to_guides/install.md
-  - file: how_to_guides/debugging.md
-- caption: Reference
-  entries:
-  - file: .doxygen/docBin/html/index
-  - file: reference/kernel_language
-  - file: reference/math_api
-  - file: reference/terms
-  - file: reference/glossary
-  - file: reference/deprecated_api_list
-- caption: Developer Guide
-  entries:
-  - file: developer_guide/build
-  - file: developer_guide/logging
-  - file: developer_guide/contributing.md
+- caption: Legacy Developer Guide
+  entries:
+    - file: developer_guide/logging
+    - file: developer_guide/contributing.md

docs/.sphinx/requirements.in

@@ -1 +1 @@
-rocm-docs-core[api_reference]==0.11.0
+rocm-docs-core[api_reference]==0.19.0

docs/.sphinx/requirements.txt

@@ -1,8 +1,8 @@
 #
-# This file is autogenerated by pip-compile with Python 3.8
+# This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
-#    pip-compile requirements.in
+#    pip-compile ./docs/.sphinx/requirements.in
 #
 accessible-pygments==0.0.3
     # via pydata-sphinx-theme
@@ -41,7 +41,7 @@ docutils==0.16
     #   myst-parser
     #   pydata-sphinx-theme
     #   sphinx
-doxysphinx==3.2.1
+doxysphinx==3.3.4
     # via rocm-docs-core
 fastjsonschema==2.16.2
     # via rocm-docs-core
@@ -53,18 +53,12 @@ idna==3.3
     # via requests
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==5.1.0
-    # via sphinx
-importlib-resources==5.10.4
-    # via rocm-docs-core
 jinja2==3.1.2
     # via
     #   myst-parser
     #   sphinx
-json5==0.9.11
+libsass==0.22.0
     # via doxysphinx
-linkify-it-py==1.0.3
-    # via myst-parser
 lxml==4.9.2
     # via doxysphinx
 markdown-it-py==2.1.0
@@ -77,7 +71,9 @@ mdit-py-plugins==0.3.5
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-myst-parser[linkify]==1.0.0
+mpire==2.7.1
+    # via doxysphinx
+myst-parser==1.0.0
     # via rocm-docs-core
 packaging==21.3
     # via
@@ -94,8 +90,11 @@ pygithub==1.58.2
 pygments==2.12.0
     # via
     #   accessible-pygments
+    #   mpire
     #   pydata-sphinx-theme
     #   sphinx
+pyjson5==1.6.3
+    # via doxysphinx
 pyjwt[crypto]==2.6.0
     # via pygithub
 pynacl==1.5.0
@@ -115,8 +114,8 @@ requests==2.28.1
     # via
     #   pygithub
     #   sphinx
-rocm-docs-core[api_reference]==0.11.0
-    # via -r requirements.in
+rocm-docs-core[api_reference]==0.19.0
+    # via -r ./docs/.sphinx/requirements.in
 smmap==5.0.0
     # via gitdb
 snowballstemmer==2.2.0
@@ -156,15 +155,11 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
+tqdm==4.65.0
+    # via mpire
 typing-extensions==4.4.0
     # via pydata-sphinx-theme
-uc-micro-py==1.0.1
-    # via linkify-it-py
 urllib3==1.26.11
     # via requests
 wrapt==1.15.0
     # via deprecated
-zipp==3.11.0
-    # via
-    #   importlib-metadata
-    #   importlib-resources

docs/index.md

@@ -3,35 +3,98 @@
 HIP is a C++ runtime API and kernel language that allows developers to create
 portable applications for AMD and NVIDIA GPUs from single source code.
 
-## Overview
+## User Manual
+
+These documents are targeted at authors of HIP libraries and applications.
+
+::::{grid} 1 1 2 2
+:gutter: 1
+
+:::{grid-item-card} Reference
+
+- {doc}`/.doxygen/docBin/html/index`
+  - {doc}`/.doxygen/docBin/html/modules`
+- {doc}`/reference/kernel_language`
+- {doc}`/reference/math_api`
+- {doc}`/reference/deprecated_api_list`
+
+:::
+
+:::{grid-item-card} Understand HIP
+:::
+
+:::{grid-item-card} How-to Guides
+
+- {doc}`/how_to_guides/install`
+
+:::
+
+:::{grid-item-card} Tutorials
+
+- {doc}`/tutorials/saxpy`
+
+:::
+
+::::
+
+## Developer Manual
+
+These documents are targeted at authors contributing to the HIP runtime and
+the accompanying host/device compiler.
+
+::::{grid} 1 1 2 2
+:gutter: 1
+
+:::{grid-item-card} Reference
+:::
+
+:::{grid-item-card} Background
+:::
+
+:::{grid-item-card} How-to Guides
+
+- {doc}`/developer_guide/build`
+
+:::
+
+:::{grid-item-card} Tutorials
+:::
+
+::::
+
+## Legacy Content
+
+Materials listed here don't fit well the new documentation system and will be
+removed once their contents are appropriately covered.
 
 ::::{grid} 1 1 2 2
 :gutter: 1
 
 :::{grid-item-card} User Guide
+
 - {doc}`/user_guide/programming_manual`
 - {doc}`/user_guide/hip_rtc`
 - {doc}`/user_guide/faq`
+
 :::
 
 :::{grid-item-card} How to Guides
-- {doc}`/how_to_guides/install`
+
 - {doc}`/how_to_guides/debugging`
+
 :::
 
 :::{grid-item-card} Reference
-- {doc}`/.doxygen/docBin/html/index`
-  - {doc}`/.doxygen/docBin/html/modules`
-- {doc}`/reference/kernel_language`
-- {doc}`/reference/math_api`
+
 - {doc}`/reference/terms`
-- {doc}`/reference/deprecated_api_list`
+
 :::
 
 :::{grid-item-card} Developer Guide
-- {doc}`/developer_guide/build`
+
 - {doc}`/developer_guide/logging`
 - {doc}`/developer_guide/contributing`
+
 :::
 
-::::
+::::