lsegal
commented
5 years ago The problem with adding a --stylesheet argument is that it's only specific to one type of document generation. The yard doc command can generate text or viz or md or other doc formats in which a --stylesheet or --dump-css would have no meaning.
YARD abstracts itself from the type of doc generation being performed, namely, HTML is the default format, but not the only supported format. More specifically, YARD doesn't enforce any formatting rules, that's up to the templating layer being used. In fact, overriding CSS isn't really understood by YARD at all, the CSS override functionality is a specific feature of the default/fulldoc/html template only. In other words, if you wrote a new template, the template itself would be responsible for providing similar overrides, if any.
I do agree, though, better documentation or more visibility for describing how to customize YARD's default html templates would be helpful here. Having an official .md document in the guide portion describing some common templating steps would be helpful. I would accept a PR for this if you're interested in taking it up.
wagenet
The "getting started" documentation does not provide instructions on how to edit the stylesheet; it links to the Templates page which seems to be complete overkill if you just want to change the \ font from Monaco to Meslo DZ and tweak the colours a bit. (The Templates page is pretty unclear on this, too — I am still none the wiser on how to do this.)
There doesn't seem to be a
--stylesheetflag onyardocas far as I can see.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:
yard server --reload.Actual Output
There were no results returned for steps 5 and 7. Step 6 returned a load of results that did not pertain to Yard, plus a link to the homepage (the perils of using a common word for the project name, I guess :)
Expected Output
As many people want to change default stylesheets, whether for accessibility reasons or to make the generated docs conform to a house style, there should be instructions on how to do it as part of the Getting Started docs (even if it's just a link to a more in-depth page).
Ideally, there would be something like
yardoc --dump-csswhich would output the stylesheet that it's going to use; the user could then save a copy of that, edit it, and tell yardoc to use it withyardoc --css <filename>.Environment details:
ruby -v): ruby 2.4.4p296 (2018-03-28 revision 63013) [x86_64-darwin16]yard -v): yard 0.9.14I have read the Contributing Guide.