Fix markdown files embedding in documentation

[rranelli]

(there is a lot of trailling whitespace remotion. Sorry, my editor does this automatically)

I've noticed that the macro directives in the documentations are not being expanded.

For example, the documentation for the PatternMatching module here does not include the contents of the pattern_matching macro defined in the md doc file.

When I'm running bundle exec yard in my machine I get:

[warn]: Syntax error in `doc/memo.md`:(10,58): syntax error, unexpected ')', expecting end-of-inpu
t                                                                                                
[warn]: Invalid/missing macro name for Functional::Memo (lib/functional/memo.rb:20)
[warn]: Invalid/missing macro name for Functional::Delay (lib/functional/delay.rb:23)
[warn]: Invalid/missing macro name for Functional::Union (lib/functional/union.rb:58)
[warn]: Invalid/missing macro name for Functional::Tuple (lib/functional/tuple.rb:24)
[warn]: Invalid/missing macro name for Functional::Record (lib/functional/record.rb:28)
[warn]: Invalid/missing macro name for Functional::Record (lib/functional/record.rb:28)
[warn]: Invalid/missing macro name for Functional::Option (lib/functional/option.rb:23)
[warn]: Invalid/missing macro name for Functional::Either (lib/functional/either.rb:83)
[warn]: Invalid/missing macro name for Functional::Protocol (lib/functional/protocol.rb:62)
[warn]: Invalid/missing macro name for Functional::FinalVar (lib/functional/final_var.rb:39)
[warn]: Invalid/missing macro name for Functional::FinalStruct (lib/functional/final_struct.rb:51)
[warn]: Invalid/missing macro name for Functional::ValueStruct (lib/functional/value_struct.rb:28)
[warn]: Invalid/missing macro name for Functional::PatternMatching (lib/functional/pattern_matchin
g.rb:15)                                                                                         
Files:          19
Modules:         8 (    0 undocumented)
Classes:         8 (    0 undocumented)
Constants:       5 (    0 undocumented)
Methods:       114 (    0 undocumented)
 100.00% documented

I realized that the file memo.md did not contain the macro declaration @!macro [new] memoize. I have added and syntax error in the yard output disappeared.

The .yardopts file contained the line ./doc/**/*.txt that probably should've been ./doc/**/*.md.
I have changed it to ./doc/**/*.md but the problem continued the same.

I tried to find information on how to declare macros in markdown files but couldn't find any.

Any other ideas?

Ps: I have also noticed that in concurrent-ruby the markdown files are actually directly included, not macro-expanded. I have tested this approach and it (obviously) worked out fine. Should I go for it?

[coveralls]

Coverage remained the same at 98.75% when pulling 1a3b17f on rranelli:master into c857a21 on jdantonio:master.

[coveralls]

Coverage remained the same at 98.75% when pulling 1a3b17f on rranelli:master into c857a21 on jdantonio:master.

[coveralls]

Coverage remained the same at 98.75% when pulling 1a3b17f on rranelli:master into c857a21 on jdantonio:master.

[coveralls]

Coverage remained the same at 98.75% when pulling 1a3b17f on rranelli:master into c857a21 on jdantonio:master.

[jdantonio]

@rranelli Please do! Feel free to move the documentation inline within the source code files as well. That's the direction we're moving with concurrent-ruby. Thank you for taking care of this!

PS: I've updated the overalls settings to it won't make all the unnecessary comments the way it's done on this PR. That should cut down on unnecessary noise.

[rranelli]

Alright, by using {include:file:doc ...} I was able to fix the documentation. The PR is mergeable now, and I removed the [wip] take from it's title.

I have not embedded the big markdown files in the source though. I think they are better fit and easier to edit in a separate file.

[rranelli]

Thanks for changing the coveralls settings ! The way it is now is so much better.

[rranelli]

Looks like rubydoc.info were not updated.

Do you need to manually update it? (I never publish docs for anything =x)

[jdantonio]

Yes, it needs manually updated. I've refreshed it so please let me know if everything looks OK: http://www.rubydoc.info/github/jdantonio/functional-ruby/master

With concurrent-ruby we moved our docs to GitHub pages. This works much better than rubydoc.info. I've been meaning to make a similar change for this gem but haven't gotten around to it yet. :-(

[rranelli]

I see. Looks like it wouldn't be hard to set up with GitHub pages.

Would you mind if I try to give it a go? From the looks of it, I could test the doc generation in my own fork.

[jdantonio]

Actually, I just set it up and pushed the new docs. :-)

http://jdantonio.github.io/functional-ruby/

[rranelli]

Nice!

Thanks again =)

[jdantonio]

@rranelli Are you still interested in trying to setup yardoc on GitHub Pages? I need to do the same things for thread_safe (see here). Would you be interested in working on that?

[rranelli]

I would be glad to help =)

I will keep you updated over there. Thanks!