Test against stubs
Closed this issue · 10 comments
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.
Pushed an initial (incomplete) set of stubs to a new repo: https://github.com/SketchUp/ruby-api-rubs
It's not entirely clear how to use this with the stubs repository?
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'
Yes - that should do the trick. I had not gotten around to flesh out a README for this yet.
Maybe we should inject the yardopts into the stubs... ?
Yes and then maybe I will try to set up the template repo as a sub repo to the stubs.
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?
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...
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.
Everything mentioned in this issue is done, correct ?
I successfully forked (the stubs repo), cloned, and generated the docs locally.