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

Wed Nov 7 14:03:17 UTC 2012

On 11/07/2012 08:30 AM, Petr Chalupa wrote:
>
>
> On 06.11.12 17:09, Eric Helms wrote:
>> Having been a proponent of repo based documentation in the past and
>> experimented and used Sphinx/readthedocs for a couple of projects, I am
>> glad to see this discussion re-surface.  Couple of questions:
>>
>> 1) Yard looks like a code documenting tool, but not a general
>> documentation tool (like a Sphinx) - did I miss something?
>
> 1) I discussed it briefly with Tomas, because I don't have experience 
> with sphinx. From what we discussed: Yard is more code-documentation 
> oriented but can do what sphinx does. Inline including and rendering 
> is supported, see [1]. But indexes of methods, classes and files afaik 
> cannot be disabled.
>
> [1] 
> http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#Embedding_Docstrings__include_____
>
This still looks like only a code documenting tool, don't get me wrong, 
I think we do need this and it would be a big win for the project overall.

I also wonder about handling non-code, non-design documentation. The 
reason I was curious of the contrast with Sphinx is that you can 
document anything with sphinx not just code.  For example, I use Sphinx 
to write and compose documents for my research.  And we have non-code, 
non-design documentation that is worth keeping up-to-date and in our 
repo as well.  Examples include Dev process, Koji guide, Install Guide, 
User Guides, Development Resources.  The way I see it, we have need to 
be able to handle the following in the order most lacking in my opinion:

1) Code Documentation
2) Design Documentation
3) Project Documentation

I know I have mentioned it before but I am still a huge fan of what 
https://read-the-docs.readthedocs.org does for you in terms of hosting, 
versioning, and exporting documentation into other formats such as PDF 
and man-pages.  The downside being that if we can to live in a pure Ruby 
world within the server portion of Katello, then Sphinx and readthedocs 
is not for us.

I have been googling and trying to find an equivalent Ruby project for 
Sphinx like documentation, organization and management to no avail.  
Does anyone know of something like that?

- Eric

>> 2) If we push to using jekyll and Github for katello.org, how do we
>> handle blog posting? Given the scenario of blog posts being done by
>> non-developer users who probably do not want to checkout a git
>> repository, make a post, and open a pull request to that repository.  As
>> well as giving access to them to post.
>
> I was assuming that every author is a developer. If not I agree it 
> could be a problem. Do we really have non-developer authors? I was 
> thinking about not giving write access to the repo to anybody else. A 
> new article would be posted by approving and merging a pull-request.
>
>> 3) If we got rid of the wiki, how would we handle design discussions and
>> temporary posting? (e.g.
>> https://fedorahosted.org/katello/wiki/ContentViews or
>> https://fedorahosted.org/katello/wiki/PulpV2Migration)
>
> That I did not consider. What about move and update all documentation 
> form wiki to katello/master rendered by Yard and for designs use 
> github wiki. After design is done it will become part of katello 
> documentation and a pull-request implementing the design. (Transfer of 
> design to katello documentation would be easy, both are just markdown 
> files)
>
>
> Btw: I've just figured out how to embed Yard server directly into 
> katello web server so a developer would have live, searchable and 
> up-to-date Yard documentation always at hand (similarly as we have 
> Katelo REST API doc at http://localhost:3000/katello/apidoc).
>
>>
>> Thanks,
>> Eric
>>
>> On 11/06/2012 09:51 AM, Petr Chalupa wrote:
>>> 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
>>>>>
>>>>
>>>
>>> _______________________________________________
>>> katello-devel mailing list
>>> katello-devel at redhat.com
>>> https://www.redhat.com/mailman/listinfo/katello-devel
>>
>>
>>
>>
>> _______________________________________________
>> katello-devel mailing list
>> katello-devel at redhat.com
>> https://www.redhat.com/mailman/listinfo/katello-devel
>>
>
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel