Restructure documents #717

st0012 · 2022-07-15T11:04:52Z

These changes was done with these focus:

The readme is compact and easy to navigate through, with links to further information
New users can quickly feel familiar with the console
Remote debugging and client integrations can have more detailed instructions (e.g. integrate with Rails)

Main Changes

Usage section is structured around a 4-step debugging flow
1. Debugger activation
2. Setting breakpoints
3. (Triggering breakpoints - which doesn't need a section)
4. Start debugging (commands and intro to console)
Remote debugging and configuration related content are extracted to dedicated files under docs
- They both have links at the introduction section and their own short sections in the readme
- VSCode and Chrome DevTools also have links to their own sections
  - They are still under the remote debugging guide because most users (e.g. Rails users) still needs to know about it to make a successful integration
  - VSCode section now has steps dedicated for Rails/web app integration
Command list is still kept in the readme because console users are still the majority in the community, and they need those commands to get started
Remote debugging contents are re-organized and extended a bit

I'll document some details in comments.

st0012 · 2022-07-15T11:06:41Z

README.md

@@ -2,548 +2,282 @@

 # debug.rb

-This library provides debugging functionality to Ruby (MRI) 2.6 and later.
-
-This debug.rb is replacement of traditional lib/debug.rb standard library which is implemented by `set_trace_func`.


I removed this part because not many developers don't even know about the old debug.rb

st0012 · 2022-07-15T11:08:48Z

README.md

+  - See [activate the debugger in your program](#activate-the-debugger-in-your-program) for details
+- Configurable:
+  - It provides many configurations and is configurable through the `~/.rdbgrc` file
+  - See the [configuration guide](/docs/configuration.md) for more information


I think we can add a docs/concurrency_support.md and add a Concurrency support: here for information and multi-thread/process and Ractor support. But I'm not sure what'd be the content in it so I haven't done it.

st0012 · 2022-07-15T11:10:56Z

README.md

-  * By `rdbg` command
-  * By loading libraries with `-r` command line option
-  * By calling Ruby's method explicitly
-* Misc


The points here are not clear to users without further explanation, so I removed them for now.

st0012 · 2022-07-15T11:13:25Z

README.md


-If you can modify the source code, you can use the debugger by adding `require 'debug'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
+### VSCode and Chrome Devtools integration


I think if we can add images or even gifs for the integrations here, it'll get people's attention to trying them out.

st0012 · 2022-07-15T11:15:51Z

docs/remote_debugging.md

+1. You will see a dialog "Debug command line" and you can choose your favorite command line your want to run.
+1. Chosen command line is invoked with `rdbg -c` and VSCode shows the details at breakpoints.
+
+### Debug a Rails/web application


This is a new section

st0012 · 2022-07-15T11:17:26Z

docs/remote_debugging.md

+
+- `RUBY_DEBUG_SOCK_DIR` - This is where the debugger will create and look for socket files.
+- `RUBY_DEBUG_SOCK_PATH` - This is the socket file's absolute path that will be used to connect to the debugger.
+  - Currently, the debugger expects socket files to have a `ruby-debug-#{USER}` prefix during socket lookup. But this may be changed in the future.


I know you don't want to maintain this, but it's important for anyone who wants to set up the debugger at scale. And I also make it clear that it's subject to change.

ko1 · 2022-07-27T06:23:51Z

Can I see the updated doc in HTML? (I want to see on the rendered page)

st0012 · 2022-07-27T08:32:19Z

You can click into my branch and it's the rendered result.

And in general you can visit a PR's branch by clicking its name:

ko1 · 2022-08-10T01:13:40Z

Thank you. I'll review it but now I'm busy so please wait a while.

st0012 · 2022-11-25T13:19:17Z

@ko1 I've rebased it against master and applied some updates. Would you mind giving it a look again?

st0012 commented Jul 15, 2022

View reviewed changes

st0012 force-pushed the restructure-documents branch from 1365634 to 0fba963 Compare August 10, 2022 22:15

Refresh README

a6e6551

st0012 force-pushed the restructure-documents branch from 0fba963 to a6e6551 Compare November 25, 2022 13:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure documents #717

Restructure documents #717

st0012 commented Jul 15, 2022 •

edited

Loading

st0012 Jul 15, 2022

st0012 Jul 15, 2022

st0012 Jul 15, 2022

st0012 Jul 15, 2022

st0012 Jul 15, 2022

st0012 Jul 15, 2022

ko1 commented Jul 27, 2022 •

edited

Loading

st0012 commented Jul 27, 2022 •

edited

Loading

ko1 commented Aug 10, 2022

st0012 commented Nov 25, 2022


		If you can modify the source code, you can use the debugger by adding `require 'debug'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
		### VSCode and Chrome Devtools integration

Restructure documents #717

Are you sure you want to change the base?

Restructure documents #717

Conversation

st0012 commented Jul 15, 2022 • edited Loading

Main Changes

st0012 Jul 15, 2022

Choose a reason for hiding this comment

st0012 Jul 15, 2022

Choose a reason for hiding this comment

st0012 Jul 15, 2022

Choose a reason for hiding this comment

st0012 Jul 15, 2022

Choose a reason for hiding this comment

st0012 Jul 15, 2022

Choose a reason for hiding this comment

st0012 Jul 15, 2022

Choose a reason for hiding this comment

ko1 commented Jul 27, 2022 • edited Loading

st0012 commented Jul 27, 2022 • edited Loading

ko1 commented Aug 10, 2022

st0012 commented Nov 25, 2022

st0012 commented Jul 15, 2022 •

edited

Loading

ko1 commented Jul 27, 2022 •

edited

Loading

st0012 commented Jul 27, 2022 •

edited

Loading