search

SketchUp / sketchup-yard-template

YARD Template used to generate SketchUp Ruby API documentations
MIT License
13 stars 5 forks source link

OneBox Meta Headers for Embedding Information #19

Closed DanRathbun closed 7 years ago

DanRathbun commented 7 years ago

Reorganizes API doc page head sections and adds embedding information as meta elements. Meant to support Discourse OneBox and Twitter Summary cards, (as a minimum) for displaying API Documentation page information.

REF: Issue #18

DanRathbun commented 7 years ago

To see how the <head> of the pages are reordered, save one html output page like Animation from the older template, and then one generated with these changes. Look at them side by side in Notepad++ or equivalent editor.

DanRathbun commented 7 years ago

There are some modules or classes (mainly from Core Ruby) that do not have any docstring, so this will cause a warning comment to appear in the html, but readers of the doc pages will not notice it unless they inspect the html. In these cases, for the OneBox there will be no summary for the description.

thomthom commented 7 years ago

hmm... I checked out the branch, but I'm getting errors when I try to run this. I'm not sure why. I need to dig into the changes.

C:/Users/tthomas2/SourceTree/sketchup-yard-template/su-template/default/layout/html/embed_meta.erb:8:in `+': no implicit conversion of YARD::CodeObjects::RootObject into String (TypeError)
        from C:/Users/tthomas2/SourceTree/sketchup-yard-template/su-template/default/layout/html/embed_meta.erb:8:in `_erb_cache_7'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:287:in `erb'
        from C:/Users/tthomas2/SourceTree/sketchup-yard-template/su-template/default/layout/html/headers.erb:17:in `_erb_cache_6'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:287:in `erb'
        from C:/Users/tthomas2/SourceTree/sketchup-yard-template/su-template/default/layout/html/layout.erb:6:in `_erb_cache_5'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:287:in `erb'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/layout/html/setup.rb:62:in `layout'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:363:in `render_section'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:259:in `block (2 levels) in run'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:256:in `each'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:256:in `block in run'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:394:in `add_options'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:255:in `run'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:136:in `run'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/fulldoc/html/setup.rb:52:in `block in serialize_index'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/engine.rb:123:in `block in with_serializer'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/logging.rb:72:in `capture'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/engine.rb:121:in `with_serializer'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/fulldoc/html/setup.rb:51:in `serialize_index'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/fulldoc/html/setup.rb:68:in `serialize_file'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/fulldoc/html/setup.rb:11:in `block in init'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/fulldoc/html/setup.rb:10:in `each'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/fulldoc/html/setup.rb:10:in `each_with_index'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/templates/default/fulldoc/html/setup.rb:10:in `init'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:193:in `initialize'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:131:in `new'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/template.rb:136:in `run'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/templates/engine.rb:105:in `generate'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/cli/yardoc.rb:349:in `run_generate'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/cli/yardoc.rb:263:in `run'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/lib/yard/cli/command.rb:14:in `run'
        from C:/Ruby23/lib/ruby/gems/2.3.0/gems/yard-0.9.8/bin/yardoc:13:in `<top (required)>'
        from C:/Ruby23/bin/yardoc:22:in `load'
        from C:/Ruby23/bin/yardoc:22:in `<main>'
thomthom commented 7 years ago

The error doesn't seem to correctly provide the correct line number... claims line 8, but I wonder if it could be line 6?

thomthom commented 7 years ago

Hm. I'm running into the scenario where object is a #<yardoc root> and @index is true. Which then fails at line 6. Still don't know why that happen though.

thomthom commented 7 years ago

Looks to be related to the README file...

2017-02-17_16h16_56

DanRathbun commented 7 years ago

I'm running into the scenario where object is a #<yardoc root> and @index is true.

Well that is dumb HUH? Who would've thunk @index would be true when it really is not an index file ?

MY BAD, But I just went by the YARD doc'ing itself.

http://www.rubydoc.info/gems/yard/0.9.5/YARD/Templates/TemplateOptions#index-instance_method

Which then fails at line 6. Still don't know why that happen though.

Yes, I ran into this same error when object was not a string and was a YARD::CodeObjects::Base subclass type, (and I was attempting to do string concatenation.) This is why the whole conditional there was born in the first place.

As you get to know YARD, you can see the weirdness, ie, using references for different kinds of things, and doing things that don't make sense.

So here, for example, @index is true, yet it is not one of the index files.

Looks to be related to the README file...

You need to realize we are running this from within the stubs repo, which does not have a README file (because you changed it's name.)

But I suppose it would not hurt to include a clause in the conditional to handle a file named "README".

DanRathbun commented 7 years ago

So, obviously we need to reorder the conditional and handle this weird step when @index is true, it's the root object, but it's really a @file object.

My question is, (since I do not have a "README.md" file in the stubs repo,) why is this erb getting called twice for "README.md", once without attributes, again with attributes ?

YARD::CodeObjects::Base#root?

DanRathbun commented 7 years ago

@thomthom Okay committed more changes. Overhauled the conditional, removed the version stamps.

DanRathbun commented 7 years ago

And perhaps now we are nearer done ?