Generating docs without source code documentation

[justin.gaylor]

Hello,

What is the easiest way to disable generation of "View source" code
sections for class/module methods? I guess some sort of tag could be
used (or created) to achieve this (such as @no_source), but I would
prefer not to rely on the developers to incude that tag (sometimes
humans forget). Is there an option or something to disable this? Or a
custom template must be created?

Thanks in advance for your help. Any guidance you can provide is
greatly appreciated!

Justin

[Loren Segal]

Hi Justin,

On 5/7/2012 6:04 PM, justin.gaylor wrote:
> What is the easiest way to disable generation of "View source" code
> sections for class/module methods? I guess some sort of tag could be
> used (or created) to achieve this (such as @no_source), but I would
> prefer not to rely on the developers to incude that tag (sometimes
> humans forget). Is there an option or something to disable this? Or a
> custom template must be created?

You have to create a custom template. You could do so as an opt-in
method with said custom tag, or just use the logic you defined above
directly, your choice. Add the file
'my_templates/default/fulldoc/method_details/setup.rb' with the
following contents:

def source
return if object.scope == :class # class method
return if object.has_tag?(:no_source) # @no_source tag
super
end

Call yard with `-p my_templates`.

Note:

You shouldn't do this, though. You either choose to display source to
your users or you don't. Picking and choosing is messy. Eventually your
users will want to see source for things you are hiding for no good
reason. If your project is open source, you shouldn't be fussy about
where source is shown. If it's closed source, well, you probably don't
want to show source anywhere. We're actually going to be adding source
displays to attributes in a future version because of this reason.

Loren

[Justin Gaylor]

Hi Loren,

Thank you for the quick response! I could achieve the desired
generation (without source) using your suggestion.

Actually, my original question was not clear. What I meant to ask was
how to disable source presentation for *all* methods, not only class/
module methods. I achieved this by creating the following method by
your example.

[my_templates/default/method_details/setup.rb]
def source
return
end

NOTE: I'm not sure if it is a difference in YARD version (using
0.7.5), but I needed to remove 'fulldoc/' from the path you gave
previously, otherwise yard wasn't finding my custom setup.rb.

Then run with 'yard -p my_templates'

Thank you!
Justin

[Loren Segal]

On 5/7/2012 8:30 PM, Justin Gaylor wrote:
> Hi Loren,
>
> Thank you for the quick response! I could achieve the desired
> generation (without source) using your suggestion.
>
> Actually, my original question was not clear. What I meant to ask was
> how to disable source presentation for *all* methods, not only class/
> module methods. I achieved this by creating the following method by
> your example.
>
> [my_templates/default/method_details/setup.rb]
> def source
> return
> end

This is how you hide source for all methods in general. We do not have
an option for it, but if someone wrote a patch for something like
--hide-source it would probably be accepted. This is usually not needed
though, and again, not really recommended in general. If you *do* have a
closed source project, you probably don't have your code generating
automatic docs on any doc sites, so adding in extra template code isn't
all that unreasonable.

>
> NOTE: I'm not sure if it is a difference in YARD version (using
> 0.7.5), but I needed to remove 'fulldoc/' from the path you gave
> previously, otherwise yard wasn't finding my custom setup.rb.

No, this was an error on my part. "fulldoc" should not have been there.
Good catch.

Loren

[thom...@sketchup.com]

Thanks for this. Exactly what I needed. 

Would be nice to see as a command line option.