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

Extra files with same file name #1277

Open
zhelyan opened this issue Sep 3, 2019 · 2 comments · May be fixed by #1289
Open

Extra files with same file name #1277

zhelyan opened this issue Sep 3, 2019 · 2 comments · May be fixed by #1289

Comments

@zhelyan
Copy link

zhelyan commented Sep 3, 2019

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:

Screenshot 2019-09-03 at 11 04 23

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

igneus commented Oct 6, 2019

I've just encountered the same issue.

igneus added a commit to igneus/calendarium-romanum that referenced this issue Oct 6, 2019
@igneus
YARD: include referenced readme files
c13949f 
still broken, affected by
lsegal/yard#1277

[ci skip]
@lsegal
Copy link
Owner

lsegal commented Oct 6, 2019

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:

image

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!

@bfad bfad linked a pull request Nov 13, 2019 that will close this issue
Open
4 tasks
igneus added a commit to igneus/calendarium-romanum that referenced this issue Jun 28, 2020
@igneus
fixes and improvements of the YARD documentation
b190c3c 
most importantly name clash between /README.md and /data/README.md
fixed the way suggested here
lsegal/yard#1277 (comment)
jspizziri pushed a commit to Lumen-de-Lumine/calendarium-romanum that referenced this issue Jul 15, 2020
@igneus @jspizziri
fixes and improvements of the YARD documentation
8651e09 
most importantly name clash between /README.md and /data/README.md
fixed the way suggested here
lsegal/yard#1277 (comment)
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
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Store extra files in their own directory bfad/yard
3 participants
@lsegal @igneus @zhelyan