Katello/katello — pull request #1430 by pitr-ch (2013-01-22 15:32:22+00:00)
Title: Add YARD documentation for Katello

# TODO

- [ ] package yard-activerecord
- [ ] package railroady
- [ ] merge this PR

# Email copy

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 plugin 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] this pull request
[2] https://github.com/pitr-ch/katello/tree/story/yard
[3] https://github.com/pitr-ch/katello/blob/story/yard/src/README.md