yard: [yardoc] Can't skip parsing README.md

Well, I have the exact same wish as @martinb3 and this seems like a perfectly reasonable scenario to support. Speaking for myself, I want the Github audience to be presented with an introduction to my project, I want my API audience to be presented with an API index.

I have indeed in the mean time reduced my wildcard. It’s counter intuitive and more work though to have to list all of them separately instead of being able to use a wildcard and expect that folders I exclude would just not be visited by yard at all. Unfortunately my develop time is limited, so I won’t be able to contribute to yard at this moment.

As a side note, I consider it a good programming principle to leave decisions up to the end user and not to limit their options. You can never foresee all the possible use cases of a tool, so the less doors you close the more people can use it.

One of YARD’s goals as a project is to make documentation better.

What if a user decides to put a concise readme on github to point to the online documentation or with instructions on running yard, where they want another readme to be the main page of their documentation. Who would be legitimate in deciding that nobody should ever do this, and thus make it impossible?

People look for tools, not for moral lessons, so if you fail to appreciate that, they turn elsewhere. You won’t force the hand of a user who knows what they want. Trying to do so is patronizing in my opinion, and that’s why people get aggravated over it. There’s a number of otherwise reasonably good tools that I won’t use for that exact reason, websites blocking tor, rspec or minitest, … Do you have a saw that auto-destructs after a certain number of uses because the makers decided that sawing with a blunt saw is bad for your back? I don’t think you’d want one, well neither do I…

Why can’t a --[no-]readme option be added, that’s not a breaking change right?

because it’s not in a sub-directory of the ‘lib’ directory

YARD is simply following a very standardized Ruby convention here, not inventing anything new. It’s also worth noting that this same convention will prevent you from using other tools like RDoc, RubyGems, etc, which all default to using lib in the same way, so I’m not sure this is a good example of a YARD-specific opinion.

YARD, however, is opinionated, as are most Ruby libraries. If opinions don’t match standard conventions, there is room to improve, but I’m not sure that’s the case here.

YARD holds the opinion that a prose based landing page is important for documenting a project. This is most commonly known as the README. This itself shouldn’t really be a controversial opinion-- GitHub holds the same opinion, we just conflict on the expected filename. This conflict is due to the difference in audience context for users cloning a repo vs. reading API documentation, frankly an age old conflict that is not unique to Ruby.

Fortunately as mentioned above, you can both change the filename in YARD (--readme) or specify an override README in GitHub (.github/README) which implies that this is contextual conflict that GitHub is aware of these edge cases. Given the very simple workarounds here, I’m not sure the solution should be a behavioral change. That said, a better highlighting of this in docs could be helpful for some users hitting this edge case.

If the opinion truly is that there should be documentation with no landing page, that is not an opinion that YARD holds, and yes, YARD is opinionated enough to not help you in this case. That said, and as listed above, there are still some very simple workarounds if you really want to work in this way. In that sense, YARD is opinionated but YARD’s opinions should not stop you from doing whatever you want with the tool with minimal effort (changing a README file or removing the index page altogether both take only 1 line of code).

Discoverability is usually the blocker, and that’s because these use cases are rarely asked about and so documenting them is not fully prioritized. If you believe discoverability of these edge cases could use work, the best way to fix it would be to add that visibility through a documentation PR, or simply write extra addendum content and open an issue to have it added to YARD’s (sparse) set of guides at https://yardoc.org/guides – I would certainly accept extra docs that help with topics such as “improving documentation on GitHub”, “customizing look and feel of docs”, and so on.

Why is this closed?

This doesn’t only concern the main README.md. The fact that --exclude does not take into account the extra files is strange, counter intuitive and problematic. If I have a project with git submodules and I --exclude them for the documentation generation, I will still get a README file with no title in my yardoc output for every submodule. That’s a no go, and sure everything is open source, we can rewrite templates and parsers and everything else, but why?

👍 because README.md has special meaning to Github, and I’d also like to show one thing to the Github audience but document my code for another audience. If you won’t fix, you should probably rename --exclude to something that more accurately reflects its purpose, such as --exclude_source.

I have to give you major props for thoroughly answering and addressing this. Makes me want to see what I can do to at least - as you stated - improve education on what opinions YARD (and yes, a good portion of Ruby work) has that might interfere in cases such as mine and OPs

As a side note, I consider it a good programming principle to leave decisions up to the end user and not to limit their options.

Conversely, opinionated software is fairly common in the Ruby ecosystem. Fortunately, YARD actually makes fairly few opinionated choices, so I feel confident in standing behind the very few decisions we do make. That said, it’s still possible to do the thing needed in this issue with minor template tweaks, so to say that we limit options is actually fairly inaccurate to begin with. It is more accurate to say that we make certain things hard to do, because they should be.

As for your example use case,

What if a user decides to put a concise readme on github to point to the online documentation or with instructions on running yard, where they want another readme to be the main page of their documentation.

This is already possible with --readme. The specific issue here is not wanting any README document at all, which simply does not fall under YARD’s goals, so it is not implemented. Again, it is still possible to do this with template customization, which is a supported path in YARD.

Do you have a saw that auto-destructs after a certain number of uses because the makers decided that sawing with a blunt saw is bad for your back? I don’t think you’d want one, well neither do I…

YARD is not a saw that auto-destructs, YARD is a table saw that does this. That is a table saw I would want, which is why I build similar safety mechanisms into the software I write. If you prefer a saw that will slice off your hand, you are correct that there certainly are other options.