Override .yardopts file with command line arguments?

[thomthom]

I got a project where I generate docs using YARD. I have set up a .yardopts file with my options for easy convenience. This include using the -p argument to make YARD use a custom template I have.

Now I'm also trying to generate stubs using YARD. I'm doing that via another custom template. When I run yardoc with -p argument that point to my stub-template it doesn't seem to override the .yardopts file.

I can only get it to use the other template by modifying the .yardopts file. I'm trying to run this from the same folder because I'm reusing the same DB between doc generation and stub generation.

I thought using a command line argument would take priority over the .yardopts file. Is this assumption incorrect? Or am I just using it wrong?

My folder structure can be simplified to this:

template1/
template2/
.yardopts

Where "template1" is a minor customization of the default HTML template that output the result to a doc/ folder. "template2" is my custom stub template that generate output to a stubs/ folder.

[thomthom]

Shortly after posting this I had a though; why use two different templates, when I can use sub-templates?

My old structure was this:

template1/
  default/
template2/
  default/
.yardopts

But with a little change:

template1/
  default/
  stubs/
.yardopts

The former "template2" is now a "stubs" sub-template, and I switch between them using the -t option:

yardoc -t stubs -f text

[thomthom]

hm... using --use-cache seem to result in no objects for my custom template plugin.

I got a single-file template: myplugin/default/fulldoc/text/setup.rb and in the init method I used options.objects = objects = run_verifier(options.objects) which I copied from the default template YARD ships with.

But when I use --use-cache I'm getting to objects. Is there another source for the parsed objects one should use with templates? (When you create templates from scratch)

[lsegal]

Can you provide a full repro case of your .yardopts and associated command line args? If you're putting --use-cache in .yardopts, don't, because YARD will break in weird ways-- though in general it should work out. It may be that you unknowingly specified no paths to parse, but it's hard to know without seeing an example.

[thomthom]

Here's a minimal example:

example.zip

Folder structure:

src/
 foo.rb   # example Ruby source
 hello.rb # example Ruby source
su-template/ # custom templates
  coverage/ # Generate a simple list of all methods
  stubs/       # Generates stubs (incomplete - WIP)
.yardopts

The way I was thinking of using this was:

Run yardoc to generate the HTML docs.

Then, run the coverage and stubs templates. I was thinking I could use the cache to speed up this.

When I invoke the coverage template without re-using cache it works fine:

yardoc -t coverage -f text

Result:

4
12
12
1
[#<yardoc root>, #<yardoc module Example>, #<yardoc class Example::Foo>, #<yardoc class Example::Hello>]
Generating coverage.manifest...
C:/Users/tthomas2/Desktop/yard-temp/coverage.manifest
Files:           2
Modules:         1 (    0 undocumented)
Classes:         2 (    0 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         9 (    0 undocumented)
 100.00% documented

And the coverage.manifest file is populates.

But when I add --use-cache it doesn't work - the coverage.manifest is empty:

yardoc -t coverage -f text --use-cache

0
12
12
1
[]
Generating coverage.manifest...
C:/Users/tthomas2/Desktop/yard-temp/coverage.manifest
Files:           2
Modules:         1 (    0 undocumented)
Classes:         2 (    0 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         9 (    0 undocumented)
 100.00% documented

I also tried yardoc -t coverage -f text --use-cache .yardoc in case it didn't pick the default cache by default. But no difference.

[lsegal]

This is definitely odd behavior. I'm trying to track this down but can't seem to. The normal yard -c behavior works fine without custom templating. I'll have to dig deeper.

[thomthom]

Yea, -c works fine with the default template as well. I wasn't sure if it was my entry point of myplugin/default/fulldoc/text/setup.rb that was missing something. Since I'm in these cases not building on top of existing template but wanting something completely new.

Using the html template seemed to become difficult because it was doing so much that I didn't need/want. And the default template didn't seem to work by just switching to text format - got errors. I was wondering if it was meant for cli help.

That's why I tried with myplugin/default/fulldoc/text/setup.rb - by result of trial in error in trying to get full control of what was generated.

I'll be digging deeper myself. Thanks for looking into it. It sounds like I wasn't that far off with how I thought this should work.

[thomthom]

I was tinkering around a little today. Found something which seemed to work.

In coverage/default/fulldoc/text/setup.rb:

I replaces this line in init

options.objects = objects = run_verifier(options.objects)

With this line:

options.objects = objects = run_verifier(Registry.all(:class, :module))

Now, I never really understood what options.objects was. options almost sounds like it's data from the command line, but given that it get populated with items when no -c is specified that doesn't sound right.

Is it returning the objects that is found when parsing?

And does it make sense to use Registry.all(:class, :module)?

[lsegal]

You can use Registry.all(:class, :module) if you want. You can also grab all objects if that's what you're looking for. It's really up to you.

As for options.objects, it is indeed filled by the YARD::CLI::Yardoc module prior to calling the template engine to render output, and it includes the toplevel registry objects.

[thomthom]

So even when using -c then options.objects should have content?

[lsegal]

Yes :)

[DanRathbun]

@thomthom: Now I'm also trying to generate stubs using YARD. I'm doing that via another custom template. When I run yardoc with -p argument that point to my stub-template it doesn't seem to override the .yardopts file.

FTR, under Ruby 2.3.3-p222 running YARD 0.9.5 ... I have no problem getting the -p switch to work and override the .yardopts file. I use a batch cmd that I can double-click it re-generate the html, ... in it is this statement: call yardoc --yardopts --db "%base%/%db%" -o "%base%/%o%" -p su-template-tweak

Folder structure:

su-template/ # thomthom's template su-template-tweak/ # my tweaks .yardopts

For me, it was the -t switch that I could not get to work. I first wished to use a su-template/tweak sub-template, so I only had to deal with those files I needed to tweak. But I couldn't get it to work.

So, I had to copy the entirety of Thomas' template, do tweaks, and use the -p switch instead.