Restructure IRB's documentation #1053
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
st0012
force-pushed
the
new-docs
branch
4 times, most recently
from
573d030 to
e38bfca
Compare
st0012
commented
Dec 22, 2024
There was a problem hiding this comment.
RDoc setting related changes are all for achieving the followings all at once:
- All doc files should live under
docfolder - When RDoc generates these files' pages, they should NOT be put under
docfolder, but treated as top-level pages in the sidebar doc/index.mdshould be the main page- Documentation under
libshould be generated as usual
The current implementation is the only set of configurations I could make this work. RDoc really needs to be a better tool 😞
| @@ -0,0 +1,2 @@ | |||
| page_dir: doc | |||
| warn_missing_rdoc_ref: true | |||
There was a problem hiding this comment.
These settings can't be specified in RDoc's rake task so we need this file.
| rdoc.title = "IRB Documentation" | ||
| rdoc.main = "index.md" | ||
| rdoc.rdoc_dir = "_site" | ||
| rdoc.options.push("lib") |
There was a problem hiding this comment.
We also need this task because we now need to use lib as the target folder, not the root folder.
st0012
force-pushed
the
new-docs
branch
4 times, most recently
from
00de801 to
600e8ce
Compare
Currently, part of the documentation lives in `lib/irb.rb` as RDoc comments, and the rest lives in `README.md`. The RDoc comments are not for viewing on GitHub, while README.md is. So this means users need to read part of the documentation on https://ruby.github.io/irb/, and the rest on GitHub. This is not a great user experience. This commit restructures the documentation so all major documentation is in `doc/index.md` that will become the main documentation for IRB on https://ruby.github.io/irb/. This solves a 2 main problems: 1. Users can read IRB documentation all in one place, on https://ruby.github.io/irb/. 2. It makes updating the documentation easier, especially the content that currently lives in `lib/irb.rb`.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Currently, part of the documentation lives in
lib/irb.rbas RDoc comments, and the rest lives inREADME.md.The RDoc comments are not for viewing on GitHub, while README.md is. So this means users need to read part of the documentation on https://ruby.github.io/irb/, and the rest on GitHub. This is not a great user experience.
This PR restructures the documentation so all major documentation is in
doc/index.mdthat will become the main documentation for IRB on https://ruby.github.io/irb/.This solves a 2 main problems:
lib/irb.rb.Next Steps
README.md's content with links to relevant sections.EXTEND_IRB.mdneeds to be updated to link to the new page. The file can't be deleted because it was advertised in multiple places.What This PR Does NOT Do
This PR is a foundation for future documentation changes. It does not include fact-checking existing documentation or correcting existing errors...etc.
Demo (generated with ruby/rdoc#1250)
Screen.Recording.2024-12-23.at.23.51.41.mov