How do I exclude a markdown file from YARD?

Question

My project has a README.template.md file which should not be parsed by YARD.

I've used --exclude for certain .rb files, but I can't seem to exclude this file.

$ yard doc --exclude README.template.md 
[warn]: In file `README.template.md':2: Cannot resolve link to { from text:
    ...{{ ossHeader }...
[warn]: In file `README.template.md':2: Cannot resolve link to { from text:
    ...{{ ossHeader }...
[warn]: In file `README.template.md':2: Cannot resolve link to { from text:
    ...{{ ossHeader }...
[warn]: In file `README.template.md':2: Cannot resolve link to { from text:
    ...{{ ossHeader }...

I've tried marking it private by adding @private at the top, YARD still parses it.

<!--
# @private
-->

{{ ossHeader }}

## Getting Started :running:

How can I get YARD to ignore this file?

$ yard config
ivars:
  :@symbolize_value: false
elements:
  :load_plugins: false
  :ignored_plugins: []
  :autoload_plugins: []
  :safe_mode: false

$ cat .yardopts 
--no-private
--exclude _pb.rb$

Answer 1

TLDR; Your only choice is to rename the README.template.md to something else :(

Why Yard does Yard things

This has been a fun deep dive back into ruby. I read through the Yardoc source, specifically the command line parser and found this.

From Yarddoc Source starting at line 287. Let's look at the relevant parts of the "parse_arguments" function

# Parses commandline arguments
# @param [Array<String>] args the list of arguments
# @return [Boolean] whether or not arguments are valid
# @since 0.5.6
def parse_arguments(*args)
# --- CODE SNIPPED AWAY ----
  readme = Dir.glob('README{,*[^~]}').
           select {|f| extra_file_valid?(f)}.
           sort_by {|r| [r.count('.'), r.index('.'), r] }.first
# --- CODE SNIPPED AWAY ----
end

The code shows it will always glob any file that starts with the letters 'README' no matter what follows. This is the default behavior, and the maintainer has no intention of changing it as of today. No judgement, I agree with the philosophy.

Solutions

I see a couple of options for you.

1. fork the yard repo, modify the dir.glob to ignore things that have template or other things. The opensource way -- all in unison THIS IS THE WAY lol :)
2. Use a YardocTask - below I modified the Rakefile from your project. Additions are annotated.

Yard provides before and after procs for the YarddocTask

Now this isn't the BEST way to solve the problem. You really shouldn't be shelling out because of... lots of reasons... but it is a working solution. I also am assuming a *nix environment when renaming the file. You should probably change it to use ruby FileUtils.

# frozen_string_literal: true

require "bundler/gem_tasks"
require "rspec/core/rake_task"
# ----------- Start new -------------
require "yard"
# ------------- end new -------------
RSpec::Core::RakeTask.new(:spec)

require "rubocop/rake_task"

RuboCop::RakeTask.new

task default: %i[spec rubocop]

# ----------- Start new -------------
YARD::Rake::YardocTask.new do |t|
  t.before = Proc.new {
    `mv README.template.md _README.template.md`
  }
  t.after = Proc.new {
    `mv _README.template.md README.template.md`
  }
end
# ------------- end new -------------

Let me know if you need a deeper explanation. I'll be happy to expand on anything you are unclear on.