[katello-devel] Adding YARD documentation for Katello

[Petr Chalupa]

Hi,

There was a discussion about documentation some time ago.

My original proposal was to move everything to repository which turn out 
not to be such a good idea, mainly because:
- we have non developer contributors to wiki and web
- yard documentation is not suitable for design tasks

However it is my understanding that we somewhat agreed on having source 
code documentation and to have developer guides in code. So I am adding 
Yard support to master in [1] pull-request.

## Proposal: What goes where?

I propose to split our documentation by intended consumer.
- Documentation directed at user would go to wiki.
- (Temporary) design pages would go to wiki.
- Code documentation and documentation directed at developers would go 
to repository and would be written in YARD.

## What have I added?

- YARD server is embedded to Katello server, you can found a link in the 
footer (only in development)
   - for a developer to have the documentation as close as possible 
(without that it is not much useful)
- YARD server will regenerate on any documentation change
   - for a developer to be able to edit documentation without pain
- I've fixed old YARD plug-in to document ActiveRecord attributes and 
associations
- see README [3]
- markdown is the default markup
- there are graphs added for models and controllers

## How to check it out?

- Checkout my branch [2]
- Run Katello server
- Find a link in the footer

## How to document?

Disclaimer: I've wrote a guide with some tips on how to write 
documentation. It's my personal view on the topic and what worked for me 
in past. Please share your tips and comments.

The guide has link in README section Guides (last place), I am also 
attaching it to this email for you not to have to checkout my branch.

Happy documenting :)
Petr


[1] https://github.com/Katello/katello/pull/1430
[2] https://github.com/pitr-ch/katello/tree/story/yard
[3] https://github.com/pitr-ch/katello/blob/story/yard/src/README.md
-------------- next part --------------
A non-text attachment was scrubbed...
Name: HowToDocument.md
Type: text/x-markdown
Size: 5472 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/katello-devel/attachments/20130122/c02a47b8/attachment.bin>