[docs][observability] O11y refactor 1/N (ray-project#35158)

krfricke · May 12, 2023 · a44b00d · a44b00d
1 parent 8f9355a
commit a44b00d
Show file tree

Hide file tree

Showing 13 changed files with 53 additions and 16 deletions.
diff --git a/doc/source/_toc.yml b/doc/source/_toc.yml
@@ -384,6 +384,19 @@ parts:
 
  - file: ray-observability/monitoring-debugging/monitoring-debugging
  title: "Monitoring and Debugging"
+ sections:
+ - file: ray-observability/user-guides/index
+ title: User Guides
+ sections:
+ - file: ray-observability/user-guides/troubleshoot-apps/index
+ title: Troubleshooting Applications
+ sections:
+ - file: ray-observability/user-guides/troubleshoot-apps/troubleshoot-failures
+ - file: ray-observability/user-guides/troubleshoot-apps/troubleshoot-hangs
+ - file: ray-observability/user-guides/troubleshoot-apps/optimize-performance
+ - file: ray-observability/user-guides/troubleshoot-apps/ray-debugging
+ - file: ray-observability/user-guides/troubleshoot-apps/ray-core-profiling
+ - file: ray-observability/user-guides/ray-tracing
 
  - file: ray-references/api
  title: References
@@ -401,5 +414,7 @@ parts:
  - file: ray-contribute/writing-code-snippets
  - file: ray-contribute/fake-autoscaler
  - file: ray-core/examples/testing-tips
+ - file: ray-contribute/debugging.rst
+ - file: ray-contribute/profiling.rst
  - file: ray-core/configure
  - file: ray-contribute/whitepaper
diff --git a/doc/source/ray-contribute/debugging.rst b/doc/source/ray-contribute/debugging.rst
@@ -1,5 +1,7 @@
-Debugging (internal)
-====================
+Debugging for Ray Developers
+============================
+
+This debugging guide is for contributors to the Ray project. 
 
 Starting processes in a debugger
 --------------------------------

diff --git a/doc/source/ray-contribute/profiling.rst b/doc/source/ray-contribute/profiling.rst
@@ -1,9 +1,9 @@
 .. _ray-core-internal-profiling:
 
-Profiling (internal)
-====================
+Profiling for Ray Developers
+============================
 
-This document details, for Ray developers, how to analyze Ray performance.
+This guide helps contributors to the Ray project analyze Ray performance.
 
 Getting a stack trace of Ray C++ processes
 ------------------------------------------

diff --git a/doc/source/ray-observability/monitoring-debugging/monitoring-debugging.rst b/doc/source/ray-observability/monitoring-debugging/monitoring-debugging.rst
@@ -13,15 +13,8 @@ See :ref:`Getting Help <ray-troubleshoot-getting-help>` if your problem is not s
  ../overview
  ../../ray-core/ray-dashboard
  ../state/state-api
- ../ray-debugging
  ../ray-logging
  ../ray-metrics
  profiling
- ../ray-tracing
- troubleshoot-failures
- troubleshoot-hangs
- troubleshoot-performance
  gotchas
  getting-help
- ../../ray-contribute/debugging.rst
- ../../ray-contribute/profiling.rst
diff --git a/doc/source/ray-observability/overview.rst b/doc/source/ray-observability/overview.rst
@@ -1,3 +1,5 @@
+.. _observability-overview:
+
 Overview
 ========
 

diff --git a/doc/source/ray-observability/user-guides/index.md b/doc/source/ray-observability/user-guides/index.md
@@ -0,0 +1,9 @@
+(observability-user-guides)=
+
+# User Guides
+
+These guides help you monitor and debug your Ray applications and clusters.
+
+The guides include:
+* {ref}`observability-troubleshoot-user-guides`
+* {ref}`ray-tracing`
diff --git a/doc/source/ray-observability/ray-tracing.rst → ...observability/user-guides/ray-tracing.rst b/doc/source/ray-observability/ray-tracing.rst → ...observability/user-guides/ray-tracing.rst
diff --git a/doc/source/ray-observability/user-guides/troubleshoot-apps/index.md b/doc/source/ray-observability/user-guides/troubleshoot-apps/index.md
@@ -0,0 +1,10 @@
+(observability-troubleshoot-user-guides)=
+
+# Troubleshooting Applications
+
+These guides help you perform common debugging or optimization tasks for your distributed application on Ray:
+* {ref}`observability-troubleshoot-failures`
+* {ref}`observability-troubleshoot-hangs`
+* {ref}`observability-optimize-performance`
+* {ref}`ray-debugger`
+* {ref}`ray-core-profiling`
diff --git a/...ng-debugging/troubleshoot-performance.rst → ...roubleshoot-apps/optimize-performance.rst b/...ng-debugging/troubleshoot-performance.rst → ...roubleshoot-apps/optimize-performance.rst
@@ -1,5 +1,7 @@
-Troubleshooting Performance
-===========================
+.. _observability-optimize-performance:
+
+Optimizing Performance
+======================
 
 No Speedup
 ----------

diff --git a/...bility/monitoring-debugging/profiling.rst → ...er-guides/troubleshoot-apps/profiling.rst b/...bility/monitoring-debugging/profiling.rst → ...er-guides/troubleshoot-apps/profiling.rst
diff --git a/...ource/ray-observability/ray-debugging.rst → ...uides/troubleshoot-apps/ray-debugging.rst b/...ource/ray-observability/ray-debugging.rst → ...uides/troubleshoot-apps/ray-debugging.rst
@@ -1,7 +1,7 @@
 .. _ray-debugger:
 
-Ray Debugger
-=============
+Using the Ray Debugger
+======================
 
 Ray has a built in debugger that allows you to debug your distributed applications. It allows
 to set breakpoints in your Ray tasks and actors and when hitting the breakpoint you can

diff --git a/...oring-debugging/troubleshoot-failures.rst → ...oubleshoot-apps/troubleshoot-failures.rst b/...oring-debugging/troubleshoot-failures.rst → ...oubleshoot-apps/troubleshoot-failures.rst
@@ -1,3 +1,5 @@
+.. _observability-troubleshoot-failures:
+
 Troubleshooting Failures
 ========================
 

diff --git a/...nitoring-debugging/troubleshoot-hangs.rst → .../troubleshoot-apps/troubleshoot-hangs.rst b/...nitoring-debugging/troubleshoot-hangs.rst → .../troubleshoot-apps/troubleshoot-hangs.rst
@@ -1,3 +1,5 @@
+.. _observability-troubleshoot-hangs:
+
 Troubleshooting Hangs
 =====================