[katello-devel] Proposal - moving katello.org and wiki to github pages

[Petr Chalupa]

Hi,

I would like to start discussion about moving katello.org and wiki to 
one place, to github pages.

How:
- use jekyll [10] to generate katello.org
- move whole wiki to Katello/katello master branch and generate the doc 
with Yard [1]
- after everything is generated publish it on github pages

See demo [5] generated by a simple tool I've already written [4]

[1] http://yardoc.org/
[4] https://github.com/pitr-ch/katello/tree/gh-pages/generator
[5] http://blog.pitr.ch/katello/
[10] https://github.com/mojombo/jekyll

Some answers to already asked questions:

 > paraphrasing lzap: wiki is more user-friendly

If `yard server --reload` is used, changes made in documentation files 
are shown after hitting reload in browser (it even picks up changes made 
in .yardopts), which I think is almost as easy as wiki edit button and 
preview on wiki.

 > paraphrasing lzap: running jekyll locally vs on github sometimes differ

There is list of options how jekyll is set on github, it's buried 
somewhere on github-pages help, did you try them? Or we could generate 
the static content locally and push it.

Petr

On 05.11.12 14:20, Eric Helms wrote:
> I see no reason this shouldn't be discussed on katello-devel.  Could you
> please move the discussion there?
>
> Thanks!
> - Eric
>
> On 11/05/2012 03:51 AM, Petr Chalupa wrote:
>> Hi guys,
>>
>> I've written documentation for Foreman integration [12]. Because there
>> was a discussion about moving documentation to github pages, I've
>> decided to give it a try and the documentation is written in Yard [1].
>> Genereated documentation is in pull-request [2].
>>
>> I've also written small documentation generator which is in gh-branch
>> in my repo [3]. Branch contains generated documentations of Rails app
>> (Yard), CLI documentation (sphinx) and API documentation (apipie).
>> Generator is in `generator` directory [4]. As a signpost I've used one
>> of the github-page templates.
>>
>> Whole generated documentation is temporary accessible on [5].
>>
>> Imho main benefits of using Yard and github-pages are:
>> (1) everything is done with Ruby and its tools (which is I think a
>> good thing, everybody on the team knows Ruby)
>> (2) documentation itself is closer to the source code
>> (3) links form guides to a class documentation can be done easily [6]
>> (4) when writing a guide, documentation of a classes or methods can be
>> easily reused [7]. The documentation is present in source code where
>> is needed the most and reused in Guides. Compare Layers section of
>> generated guide [8] with its source [9]
>>
>> I would like to know what do you think about this approach?
>>
>> Also I would like to propose:
>> - to replace static signpost with Jekyll [10] and use it to generate
>> katello.org page
>> - move our wiki pages to katello repository and generate them using
>> Yard so they'll be part of Katello documentation
>>
>> This would bring that all resources around Katello to be centered
>> around github. There would be only repositories with source codes and
>> one repo with all documentation and katello.org pages.
>>
>> Remaning tasks:
>> - decide where to publish the documentation (currently only in my
>> repo), publish to gh-branch of Katello/katello or to
>> Katello/Katello.github.com repo, see [11]. Katello/Katello.github.com
>> makes more sense to me.
>> - auto generate documentation after each commit in master (could be
>> simple script on ozzak)
>> - add documentation for each version of katello 1.0 and 1.1
>>
>> [1] http://yardoc.org/
>> [2] https://github.com/Katello/katello/pull/995
>> [3] https://github.com/pitr-ch/katello/tree/gh-pages
>> [4] https://github.com/pitr-ch/katello/tree/gh-pages/generator
>> [5] http://blog.pitr.ch/katello/
>> [6]
>> http://blog.pitr.ch/katello/yardoc/file.ForemanIntegration.html#Resources__ForemanModel
>>
>> [7]
>> http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#Embedding_Docstrings__include_____
>>
>> [8]
>> http://blog.pitr.ch/katello/yardoc/file.ForemanIntegration.html#Resources__Foreman___
>>
>> [9]
>> https://github.com/pitr-ch/katello/blob/story/foreman_doc/src/doc/ForemanIntegration.md#resourcesforeman
>>
>> [10] https://github.com/mojombo/jekyll
>> [11] https://help.github.com/articles/user-organization-and-project-pages
>> [12] http://blog.pitr.ch/katello/yardoc/file.ForemanIntegration.html
>>
>> Petr
>>
>