76790e4cff
Useful things the commit brings:
1. Source documentation can now include images and out-of-source examples
2. Source documentation can now be supplemented by "appendixes" for
documenting advanced or uncommon usage, auxiliary examples, or any
supplementary content
3. An implementation of the YARD @see tag that utilizes the canvas
YARD linkify helper
Necessary changes for integration were:
* Gemfile now includes 'yard-appendix'
* Rake task for generating API docs (doc:api) made more readable and
now supports asset migration (images and examples)
* Canvas YARD 'api' template now handles :appendix sections provided
by the plugin
* Canvas YARD 'linkify' helper modified:
* uses a shared linker to look up a topic and controller
* overrides default handling of 'Appendix: ' links
* defaults to using the @object title as the link body when no title
was explicitly passed instead of the path.to.object
* Canvas YARD 'fulldoc' handler respects a
DOC_OPTIONS[:all_resource_appendixes] that when turned on would
generate appendix entries in the All Resources section[1]
[1] I've already implemented this functionality because I misread the
requirement (as seen in PB 6) so I thought we could keep it around and
toggle it if need be. The options are inside lib/tasks/docs.rake
---
Testing:
To verify that the changes do not alter or affect the current API docs,
fire up a terminal and do the following (inline comments for directions):
```bash
cd /path/to/canvas;
# generate the original docs before pulling these changes
bundle exec rake doc:api
mv public/doc public/doc_original
# checkout these changes into a branch... after that:
bundle install
bundle exec rake doc:api
diff -r -y -q public/doc_original/api public/doc/api
```
The output of the last command should look like this:
Only in doc/api: examples
Only in doc/api: images
To test the actual @!appendix functionality:
* see https://github.com/amireh/yard-appendix for directions on how to
define Appendix entries
* write an Appendix in any controller, optionally reference it in some
method (using @see or {link})
* Appendix entry should be shown at the bottom of the controller's doc
page
* reference to the appendix entry should take you to it
Alternatively, you can check-out the gerrit change 17454 at
https://gerrit.instructure.com/#/c/17454/ which utilizes this
functionality.
Change-Id: Id667b77ff8d36b0f503e0f6752045e3d05bc3649
Reviewed-on: https://gerrit.instructure.com/17453
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Brian Palmer <brianp@instructure.com>
QA-Review: Simon Williams <simon@instructure.com>
|
||
|---|---|---|
| .. | ||
| setup.rb | ||