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

[Proposal] bundle exec rdoc command should work for rdoc itself #1123

Closed
okuramasafumi opened this issue Jun 24, 2024 · 4 comments · Fixed by #1156 · May be fixed by #1125
Closed

[Proposal] bundle exec rdoc command should work for rdoc itself #1123

okuramasafumi opened this issue Jun 24, 2024 · 4 comments · Fixed by #1156 · May be fixed by #1125

Comments

@okuramasafumi
Copy link
Contributor

Problem

Currently, running bundle exec rdoc in the repository root causes the following error:

uh-oh! RDoc had a problem:

Directory doc already exists, but it looks like it isn't an RDoc directory.

Because RDoc doesn't want to risk destroying any of your existing files,
you'll need to specify a different output directory name (using the --op <dir>
option)


run with --debug for full backtrace

Solution

That seems caused by doc directory. Inside it there's rdoc/markup_reference.rb file only.
While this file seems to be processed by Rakefile, it doesn't have to exist in doc directory since the file path is hardcoded.
So moving rdoc/markup_reference.rb file into some other place should be enough.
@okuramasafumi okuramasafumi mentioned this issue Jun 26, 2024
Open
@hsbt
Copy link
Member

hsbt commented Jun 26, 2024

You can use rake rdoc, not rdoc for that.

@okuramasafumi
Copy link
Contributor Author

@hsbt Thank you for the info. README says nothing about rake rdoc command, though, and it's weird to me that RDoc cannot run the command on README for itself.
And doc/rdoc/markup_reference.rb doesn't make sense since that file is not a document. So I believe the change in #1125 worth it, although it might be hard to deal with ruby/ruby script issue.

@st0012
Copy link
Member

st0012 commented Jul 6, 2024

I tend to agree with @okuramasafumi here. From the original PR that introduced the file (#824), it doesn't look like it has to be under doc, just outside lib should be enough.
And not being able to run rdoc easily from the repo means that contributors and maintainers will likely test it less often, and thus make it more prone to error in the long-term.

@hsbt
Copy link
Member

hsbt commented Jul 9, 2024

I don't agree for that. We should use rake rdoc to generate documentation on this repository. Because rdoc need generated parser files now. So, rdoc command is not working standalone with fresh repository.

@st0012 st0012 mentioned this issue Aug 19, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Milestone
No milestone
3 participants
@hsbt @okuramasafumi @st0012