Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure documents #717

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Restructure documents #717

wants to merge 1 commit into from

Conversation

st0012
Copy link
Member

@st0012 st0012 commented Jul 15, 2022 •
edited
Loading

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
st0012 commented Jul 15, 2022
View reviewed changes
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`.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

README.md
* By `rdbg` command
* By loading libraries with `-r` command line option
* By calling Ruby's method explicitly
* Misc
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a new section

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.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

ko1 commented Jul 27, 2022 •
edited
Loading

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

@st0012
Copy link
Member Author

st0012 commented Jul 27, 2022 •
edited
Loading

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:

截圖 2022-07-27 09 31 00

@ko1
Copy link
Collaborator

ko1 commented Aug 10, 2022

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

@st0012
Copy link
Member Author

st0012 commented Nov 25, 2022

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
2 participants
@st0012 @ko1