canvas-lms/doc/examples/README

You can use this folder to store example snippets of code which you can
link to in the source documentation using the YARD include directive:

`{include:file:examples/my_example.md}`

The examples aren't restricted to code only, they can be any Markdown
or plain text documents.

--
This folder and its contents will automatically be copied to the output     
documentation HTML directory by the documentation generation scripts.
integrate yard-appendix plugin with canvas YARD cfg 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> 2013-02-05 14:35:51 +08:00			`You can use this folder to store example snippets of code which you can`
			`link to in the source documentation using the YARD include directive:`

			`{include:file:examples/my_example.md}`

			`The examples aren't restricted to code only, they can be any Markdown`
			`or plain text documents.`

			`--`
			`This folder and its contents will automatically be copied to the output`
			`documentation HTML directory by the documentation generation scripts.`