lsegal / yard

YARD is a Ruby Documentation tool. The Y stands for "Yay!"
http://yardoc.org
MIT License
1.95k stars 398 forks source link

`--one-file` does not interpret Markdown by default #1427

Open jacob-carlborg opened 2 years ago

jacob-carlborg commented 2 years ago

The --one-file flag does not interpret Markdown by default in the README.md file (I have not checked other non-source files).

Steps to reproduce

  1. Run the following commands:
    
    cat << EOF >> foo.rb
    # Foobar
    # * asd
    class Foo
    end
    EOF

cat << EOF >> README.md

Foo

EOF

yard doc --one-file --no-save -o . foo.rb


2. Open the generated `index.html` in the browser

## Actual Output

The Markdown in the `README.md` has not been interpreted.

<img width="569" alt="yard_no_md" src="https://user-images.githubusercontent.com/306980/150670605-c8656cd7-7956-4a82-b434-c77685b1bae8.png">

Notice how `# Foo` is output from the `README.md`, but the Markdown in the `foo.rb` file has been interpreted and output as expected.

## Expected Output

I expect the Markdown to be interpreted, this is what happens without the `--one-file` flag:

<img width="566" alt="yard_md" src="https://user-images.githubusercontent.com/306980/150670506-42c337b9-db0a-4568-aa25-be130c344b4b.png">

## Environment details:

- OS: macOS 12.0.1
- Ruby version (`ruby -v`): ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-darwin20]
- YARD version (`yard -v`): yard 0.9.27
lsegal commented 2 years ago

This is not an issue with --one-file or YARD. By default, YARD uses rdoc style markup in .rb files. If you wish to use Markdown as your markup format, you must specify it via -m markdown, see yard doc --help.

jacob-carlborg commented 2 years ago

I disagree. As you can see on the screenshots, the behavior is different with and without --one-file. I can post a screen recording that shows the whole flow.

jacob-carlborg commented 2 years ago

Here's a screen recording that shows how I generate the documentation both with and without the --one-file flag. I show both results in the browser side by side:

https://user-images.githubusercontent.com/306980/150955201-062274c5-c202-4571-8b2f-fe446ae973ee.mov