# Migrate the documentation from Hiki to YARD **URL:** \ **Category:** Ruby-Gnome 2\ **Created:** [September 20, 2011, 4:47pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036 "2011-09-20T16:47:02Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![dubstep](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/cdc98d/32.png) [@dubstep](https://www.ruby-forum.com/u/dubstep)\ **Post date:** [September 20, 2011, 4:47pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/1 "2011-09-20T16:47:02Z")
Hi, I would like to migrate the documentation from Hiki to YARD. So, I made a tool, and uploaded files to [Ruby-GNOME 2 - Browse /yard at SourceForge.net](https://sourceforge.net/projects/ruby-gnome2/files/yard/). - yagi\_gnome-0.0.1.pre.gem a tool to automate tasks and source parser(still incomplete) - vte-1.0.0.gem example package with YARD style comments - vte-doc.tar.bz2 example YARD documents Migration steps: 1.Change the Rules like vte. - Change file name to like ‘rbvte-terminal.c’ - Change file header comments - Define RG\_TARGET\_NAMESPACE macro - Use RG\_DEF\_\* macros 2.Embed YARD style comments from GIR(GObject Introspection), and add ‘@todo fixme’ tag. 3.Fix the comments referring to Hiki documents and the source code, and delete ‘@todo fixme’ tag. Will be able to use the following: $ gem install yagi\_gnome $ gem install vte $ yard config -a autoload\_plugins gnome $ yard server -g Go to [http://localhost:8808/](http://localhost:8808/). But there are some problems: - yagi\_gnome support only Ruby 1.9.2 or later. - Documents aren’t generated on Windows, because gem is binary package. - YARD server is too slow. I have a few questions. - What do you think of this migration steps? - Could you help me migration step3? Thanks, yagi(Masaaki A.) ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 20, 2011, 10:35pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/2 "2011-09-20T22:35:02Z")
> Migration steps: > 1.Change the Rules like vte. > > - Change file name to like ‘rbvte-terminal.c’ Is changing file names really needed? Not that I care much but it makes following project history harder when all files are suddenly renamed at some point. > $ gem install vte > $ yard config -a autoload\_plugins gnome > $ yard server -g > Go to [http://localhost:8808/](http://localhost:8808/). > > But there are some problems: > > - yagi\_gnome support only Ruby 1.9.2 or later. It’s quite OK. 1.8.7 support would be nice but one thing at a time. > - Documents aren’t generated on Windows, because gem is binary package. It should still be possible to get the sources or perhaps include the docs in the binary gem or something. > - YARD server is too slow. How slow? Slower than SF? It’s quite hard to beat SF in that regard. Even if slow it is quite helpful when the help can be browsed locally. Also can’t some alternative server display the pages? Thanks Michal ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 21, 2011, 12:43am UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/3 "2011-09-21T00:43:14Z")
In principle I am fine with this. A few comments though: - Right now I can update the wiki (ko1 gave me the password and login years ago) and I do so every now and then fixing little things. Will this be easy on YARD too? The wiki is very, very helpful for ruby-gnome. Without it, I could not have started with ruby-gnome. - Will there still be a remote wiki that people can watch and browse though? This is very useful for me right now. ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 23, 2011, 1:31pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/4 "2011-09-23T13:31:20Z")
Hi, Sorry for late reply. > - Right now I can update the wiki (ko1 gave me the password and login > years ago) and I do so every now and then fixing little things. Will > this be easy on YARD too? Yes, probably. > - Will there still be a remote wiki that people can watch and browse > though? It is still to be determined. Thanks, yagi ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 23, 2011, 1:30pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/5 "2011-09-23T13:30:06Z")
Hi, Sorry for late reply. > > - Change file name to like ‘rbvte-terminal.c’ > > Is changing file names really needed? > Not that I care much but it makes following project history harder > when all files are suddenly renamed at some point. Changing file names is not really needed for this migration. But yagi\_gnome includes feature to generate source files from GIR, and it needs naming rules. So, I would like to change file names. > > - Documents aren’t generated on Windows, because gem is binary package. > > It should still be possible to get the sources or perhaps include the > docs in the binary gem or something. > > > - YARD server is too slow. > > How slow? It depends on conditions(number of methods, inherited class, included modules, and others). > Also can’t some alternative server display the pages? We will probably distribute generated docs(like vte-doc.tar.bz2) and/or serve the pages. Thanks, yagi ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 23, 2011, 1:59pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/6 "2011-09-23T13:59:11Z")
On Fri, Sep 23, 2011 at 13:29, Masaaki A. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > > > - Change file name to like ‘rbvte-terminal.c’ > > Is changing file names really needed? > > Not that I care much but it makes following project history harder > > when all files are suddenly renamed at some point. > Changing file names is not really needed for this migration. > But yagi\_gnome includes feature to generate source files from GIR, and > it needs naming rules. > So, I would like to change file names. I’m not happy about having to change the names, but I think the naming should follow that in the relevant library that we are wrapping, and if we can get things for free, then changing the names of files is definitely worth it. On the C side, Atk, GIO/GLib/GObject, goocanvas, GStreamer, Gtk, GtkSourceView, and Vte all use the atkaction.c style. Gdk-pixbuf, Pango, librsvg use the gdk-pixbuf-animation.c style. Poppler is written in C++ and uses the PopplerCache.cc style. (The gdk\_pixbuf2 library should really have been called gdk-pixbuf2, but that’s beside the point.) My opinion is that we should follow the first style, namely atkaction.c. If there is any value in adding a “rb” prefix, then fine, call it rbatkaction.c. I’ve never seen the value of adding yet another prefix, however, so I didn’t do so for gio2. Whatever we decide, I think that we should have one rule that applies to all files in the project. ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 23, 2011, 2:13pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/7 "2011-09-23T14:13:22Z")
On Tue, Sep 20, 2011 at 16:46, Masaaki A. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > - yagi\_gnome-0.0.1.pre.gem > a tool to automate tasks and source parser(still incomplete) Please take the following criticism as my thoughts only. I think that this tool has a lot of potential and I would to see it be used for the Ruby-GNOME2 project. I think that a tool like this is necessary for us to be able to bring the documentation up to the quality that we desire. The coding style isn’t like the standard: - You use a tabwidth of 2 instead of spaces - You use a “\_” prefix for method parameters - You use explicit return - You define constants that only act as shortcuts to other constants, for example, CO = YARD::CodeObjects - You define multiple classes per file - You use common prefixes for all methods in a class, which just gets in the way; see, for example, lib/yagni\_gnome/template/code\_object.rb (are you doing that because you’re monkey-patching YARD::CodeObjects?) There are also a lot of singleton methods. I feel that such code is begging for a refactoring. (Singleton objects in disguise.) There’s also a lot of commented-out code. You also monkey-patch String, which I don’t think is a very good thing to do. There’s also a lot more monkep-patching going on, of, for example, Hash, Nokogiri::XML::Node, YARD::Docstring. ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 23, 2011, 1:43pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/8 "2011-09-23T13:43:06Z")
On Fri, Sep 23, 2011 at 13:30, Masaaki A. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > > - Will there still be a remote wiki that people can watch and browse > > though? > It is still to be determined. This is hardly a deal-breaker. Looking at the history, the wiki isn’t being updated a lot. Having the documentation with the code makes it so much easier to keep them in sync. ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 24, 2011, 10:16am UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/9 "2011-09-24T10:16:19Z")
Hi, 2011/9/23 Nikolai W. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid): > My opinion is that we should follow the first style, namely > atkaction.c. If there is any value in adding a “rb” prefix, then > fine, call it rbatkaction.c. I’ve never seen the value of adding yet > another prefix, however, so I didn’t do so for gio2. Currently, most files have “rb” prefix, so I think it is better to follow. > Whatever we decide, I think that we should have one rule that applies > to all files in the project. I agree with you. I would like to change to rbatkaction.c style. What do you think? Thanks, yagi ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 24, 2011, 10:18am UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/10 "2011-09-24T10:18:10Z")
Hi, 2011/9/23 Nikolai W. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid): > (are you doing that because you’re monkey-patching YARD::CodeObjects?) > > There are also a lot of singleton methods. I feel that such code is > begging for a refactoring. (Singleton objects in disguise.) > > There’s also a lot of commented-out code. > > You also monkey-patch String, which I don’t think is a very good thing > to do. There’s also a lot more monkep-patching going on, of, for > example, Hash, Nokogiri::XML::Node, YARD::Docstring. Thanks for your advice. Will be helpful. yagi ---
**Author:** ![Masaaki\_A](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/97f17d/32.png) [@Masaaki\_A](https://www.ruby-forum.com/u/Masaaki_A)\ **Post date:** [September 24, 2011, 10:48pm UTC](https://www.ruby-forum.com/t/migrate-the-documentation-from-hiki-to-yard/212036/11 "2011-09-24T22:48:53Z")
> - You define constants that only act as shortcuts to other > constants,for example, CO = YARD::CodeObjects I do this a lot in my code. It is less to type and no way in life will I type something as long as YARD::CodeObjects when I could use something shorter (if I have to reuse it in my project files). I have not looked at the code though, just a general remark since you seem to dislike that … I even go as far as do T = true and F = false and use that for my larger projects. And alias e puts. This probably makes other people crazy but I love it. And I love that ruby does not want to enforce a specific style - though with that being said, I try to not deviate from standard ruby much and I try to be careful when “monkey patching” anything (I myself do not really use this term, it sounds derogative when it is in reality powerful to me) 🙂 > - You define multiple classes per file I agree! I think it is better if it is possible to follow a simple scheme for this. I usually have one class per file, and keep the file name as lowercased variant, with \_ added. Example: class FooBar Would be stored in the file: foo\_bar.rb The big advantage here is that this scheme is VERY easy to understand for everyone and very “logical”. But I think this is all fairly minor, it’s just style. As long as the resulting documentation is as useful as the wiki is (and I love the ruby-gtk wiki, even though it is not perfect, I get server errors when modifying the pages, even though it works) then I think this is GREAT work by Masaaki A.!