Extra files with same file name

[zhelyan]

There's an issue when adding multiple extra files from different locations but having the same file name / e.g. README.md/. The generated documentation lists the extra files but links all to the same content.

Steps to reproduce

This is the minimal reproduction for the issue. I've done my best to remove all extraneous code and unique environment state on my machine before providing these steps:

1. create 3 README.md files with different content - README.md, doc/README.mdandtasks/README.md`
2. run yard doc README.md,docs/README.md,tasks/README.md -o documentation/
3. open documentation/index.html in the browser
4. Click on the Files link

The 3 readme files will be listed. The one in the root folder will be recognised as the main document but the other 2 links will point to the same content.

Actual Output

[debug]: Parsing ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp,rb}"] with `ruby` parser
[debug]: Serializing to .yardoc/objects/root.dat
[debug]: Re-generating object ...
[debug]: Generating asset js/jquery.js
[debug]: Serializing to documentation/js/jquery.js
[debug]: Generating asset js/app.js
[debug]: Serializing to documentation/js/app.js
[debug]: Generating asset js/full_list.js
[debug]: Serializing to documentation/js/full_list.js
[debug]: Generating asset css/style.css
[debug]: Serializing to documentation/css/style.css
[debug]: Generating asset css/common.css
[debug]: Serializing to documentation/css/common.css
[debug]: Generating asset css/full_list.css
[debug]: Serializing to documentation/css/full_list.css
[debug]: Generating asset class_list.html
[debug]: Serializing to documentation/class_list.html
[debug]: Generating asset method_list.html
[debug]: Serializing to documentation/method_list.html
[debug]: Generating asset file_list.html
[debug]: Serializing to documentation/file_list.html
[debug]: Generating asset frames.html
[debug]: Serializing to documentation/frames.html
[debug]: Serializing to documentation/_index.html
[debug]: Serializing to documentation/index.html
[debug]: Serializing to documentation/file.README.html
[debug]: Serializing to documentation/file.README.html
[debug]: Serializing to documentation/file.README.html
[debug]: Serializing to documentation/top-level-namespace.html
Files:           0
Modules:         0 (    0 undocumented)
Classes:         0 (    0 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         0 (    0 undocumented)
 100.00% documented

Generated documentation linking 2 of the readmes to the same content:

Expected Output

Expecting yard to respect the file paths and link the files to the correct content

Environment details:

• OS: MacOs 10.14.6
• Ruby version 2.6.2
• YARD version (yard -v): 0.9.20
• Relevant software dependency/versions: none

I have read the Contributing Guide.

[igneus]

I've just encountered the same issue.

[lsegal]

This is a known limitation in YARD's extra file serializer, which flattens all extra files into the same directory. There are ways you can monkeypatch YARD::Serializers::FileSystemSerializer#serialized_path to support serializing to subdirectories, but the simpler workaround would be to use YARD's {include:file:...} directives in separate markdown files to avoid the issue.

For example:

in .yardopts:

- docs/*.md

in docs/README-a.md:

# @title a/README.md
{include:file:a/README.md}

in docs/README-b.md:

# @title b/README.md
{include:file:b/README.md}

This generates something like the following:

It's not the cleanest workaround but it works with vanilla YARD without monkeypatches.

FWIW I would accept a PR to "fix" the root issue if it (a) is backward compatible and (b) handles the more common case of supporting singular nested READMEs without displaying as a nested README.

Hope that helps!