search

SketchUp / sketchup-yard-template

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

Test against stubs #1

Closed thomthom closed 7 years ago

thomthom commented 7 years ago

Since our documentation is generated from our source code this template can't be used by outsiders int eh same way.

Currently working on generating stubs for the Ruby API - which should in turn be possible to use as a source to generate docs yourself with this template.

More to come.

thomthom commented 7 years ago

Pushed an initial (incomplete) set of stubs to a new repo: https://github.com/SketchUp/ruby-api-rubs

jimfoltz commented 7 years ago

It's not entirely clear how to use this with the stubs repository?

jimfoltz commented 7 years ago

Ok I think I got it. I copied the .yardopts from this repo to my copy of the stubs repo, and then changed the path to the template files. 

--title "SketchUp Ruby API Documentation"
--no-api
--no-private
--tag par --hide-tag par
-e ../sketchup-yard-template/su-api_plugin.rb
-p ../sketchup-yard-template/su-template
'SketchUp'
thomthom commented 7 years ago

Yes - that should do the trick. I had not gotten around to flesh out a README for this yet.

thomthom commented 7 years ago

Maybe we should inject the yardopts into the stubs... ?

jimfoltz commented 7 years ago

Yes and then maybe I will try to set up the template repo as a sub repo to the stubs.

jimfoltz commented 7 years ago

But back on topic, you want to compare the docs generated from the source against the docs generated from the stubs? Maybe the Gnu diff Utility?

thomthom commented 7 years ago

I haven't fully thought this through though. To automate re-injection of the API comments one would need to id what the comment relate to (method, module, class or constant). Then figure out the location of of that comment in the original source.

I maybe over-complicating this...

jimfoltz commented 7 years ago

Git is able to generate a patch file which can be applied back to the source. There are several formats of patch files. But you may need some type of file name and line number hint from the source file in order to create a correct patch.

DanRathbun commented 7 years ago

Everything mentioned in this issue is done, correct ? I successfully forked (the stubs repo), cloned, and generated the docs locally.