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

Wed Nov 7 15:28:01 UTC 2012

On 07.11.12 15:03, Eric Helms wrote:
> 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

What you've described can be done with Yard, sorry I expressed poorly.

Yard needs to be supplied with two collection of files: paths to source 
files and paths to additional doc files. Typically ./app/**/*.rb, 
./lib/**/*.rb would be used for source codes and 
./doc/**/*.md,./LICENSE,./README for additional doc files.

Then files describing Dev process, Koji guide, Install Guide, User 
Guides, Development Resources would be placed into doc directory and 
linked from README (which is defaultly shown as home-page by Yard). This 
creates same structure as on wiki.

See small demo:
- README file
   - source https://github.com/pitr-ch/katello/tree/story/foreman_doc/src
   - result http://blog.pitr.ch/katello/yardoc/index.html
- a linked guide ForemanIntegration
   - source 
https://github.com/pitr-ch/katello/blob/story/foreman_doc/src/doc/ForemanIntegration.md
   - result http://blog.pitr.ch/katello/yardoc/file.ForemanIntegration.html

> 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.

There is (I think) similar project for ruby http://rubydoc.info/ which 
we may also consider. Although there may be some troubles to get it 
render Yardoc as intended.

> 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
>
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel