{"id":806,"date":"2012-07-20T22:37:38","date_gmt":"2012-07-21T02:37:38","guid":{"rendered":"http:\/\/www.jetmore.org\/john\/blog\/?p=806"},"modified":"2013-06-24T22:03:10","modified_gmt":"2013-06-25T02:03:10","slug":"rhythmbox-python-bindings-documentation","status":"publish","type":"post","link":"https:\/\/www.jetmore.org\/john\/blog\/2012\/07\/rhythmbox-python-bindings-documentation\/","title":{"rendered":"Rhythmbox Python Bindings Documentation"},"content":{"rendered":"<p>I have an itch I want to scratch in Rhythmbox, and I&#8217;ve been looking at the Python bindings for writing plugins.  It&#8217;s clear that you can do a lot of stuff, but there is no documentation specific to the Python bindings.  There is the <a href=\"https:\/\/live.gnome.org\/RhythmboxPlugins\/WritingGuide\">Plugin Writing Guide<\/a>, which is conceptually useful, and there are the <a href=\"http:\/\/developer.gnome.org\/rhythmbox\/unstable\/\">C-specific development docs<\/a>, but there&#8217;s a piece missing.<br \/>\n<!--more--><\/p>\n<p><strong>Update 2013-06-23:<\/strong> From the comments, there&#8217;s now a nice tool available to generate the docs from several versions, available from <a href=\"http:\/\/www.donaghhorgan.com\/projects\/rhythmbox\/rhythmbox-documentation-generator\/\">http:\/\/www.donaghhorgan.com\/projects\/rhythmbox\/rhythmbox-documentation-generator\/<\/a>, and several pre-generated sets available for download at <a href=\"http:\/\/www.donaghhorgan.com\/misc\/rhythmbox-python-documentation\/\">http:\/\/www.donaghhorgan.com\/misc\/rhythmbox-python-documentation\/<\/a>.  Great work Donagh, thanks for leaving the links!<\/p>\n<h2>tl;dr<\/h2>\n<p>I ended up figuring out how to generate the docs for the python bindings from the .gir files produced by the build.<\/p>\n<p>A browseable copy of the docs:<\/p>\n<ul>\n<li><a href=\"http:\/\/jetmore.org\/john\/misc\/rb\/rb297-python-bindings\">http:\/\/jetmore.org\/john\/misc\/rb\/rb297-python-bindings<\/a><\/li>\n<\/ul>\n<p>A copy of the .gir XML files generated by a rhythmbox build:<\/p>\n<ul>\n<li><a href=\"http:\/\/jetmore.org\/john\/misc\/rb\/RB-3.0.gir\">http:\/\/jetmore.org\/john\/misc\/rb\/RB-3.0.gir<\/a><\/li>\n<li><a href=\"http:\/\/jetmore.org\/john\/misc\/rb\/MPID-3.0.gir\">http:\/\/jetmore.org\/john\/misc\/rb\/MPID-3.0.gir<\/a><\/li>\n<\/ul>\n<p>A tarball of the docs:<\/p>\n<ul>\n<li><a href=\"http:\/\/jetmore.org\/john\/misc\/rb\/rb297-python-bindings.tar.gz\">http:\/\/jetmore.org\/john\/misc\/rb\/rb297-python-bindings.tar.gz<\/a><\/li>\n<\/ul>\n<p>The rest of this post is justification for going to all of this trouble, plus the actual commands I used to generate the html from the .gir files<\/p>\n<h2>Tell me a story&#8230;<\/h2>\n<p>Trying to learn from what&#8217;s already there, I found that the Magnatune plugin might be a useful thing to study.  Among other things, activating it causes a new Group &#8220;Stores&#8221; to show up in the sources list, with a member of Magnatunes.  I want to do something similar.  Looking at the code showed me a lot of interesting things, but not how to learn more about those things.  Take for instance this line, which is pretty obviously related to &#8220;turning on&#8221; the Stores group:<\/p>\n<pre class=\"brush: python; title: ; notranslate\" title=\"\">\r\ngroup = RB.DisplayPageGroup.get_by_id (&quot;stores&quot;)\r\n<\/pre>\n<p>Well, ok, but where do <code>RB<\/code>, <code>DisplayPageGroup<\/code>, and <code>get_by_id<\/code> come from?  A little bit of grepping through the git repo showed that the &#8220;real&#8221; call was likely <code>rb_display_page_group_get_by_id()<\/code>, defined in sources\/rb-display-page-group.c.  That&#8217;s nice, but no real indication of how the two were hooked together, or how to figure out what the other bindings would be named.<\/p>\n<p>After nosing into the bindings\/ directory I realized that the bindings were generated programmatically at build time.  Hoping that the build would leave behind usable map files, I downloaded the distribution, spent way too long figuring out the pre-reqs, and finally got it configured.  I ran <code>make<\/code> in bindings\/ and was rewarded with gi\/RB-3.0.gir and MPID-3.0.gir, which appeared to be XML documents defining the C-Python bindings.  This was about the best I had hoped for, but since it was still so hard to read I decided to see if there was an automatic documenter for .gir files.  Turns out there is.  With a little bit of fiddling (and this <a href=\"https:\/\/live.gnome.org\/GObjectIntrospection\/Doctools\">page<\/a>) I managed to turn out fairly usable HTML documentation for the bindings.  Doesn&#8217;t get me any closer to my plugin, but at least it lets me feel like I accomplished something tonight.<\/p>\n<p>Since I couldn&#8217;t google up these docs anywhere else, I&#8217;m posting all of my work product and the results here.  Share and enjoy!<\/p>\n<p>After <code>.\/configure<\/code> and <code>cd bindings ; make<\/code>, I was left with the two files I needed for this, <a href=\"http:\/\/www.jetmore.org\/john\/misc\/rb\/MPID-3.0.gir\">bindings\/gi\/MPID-3.0.gir<\/a> and <a href=\"http:\/\/www.jetmore.org\/john\/misc\/rb\/RB-3.0.gir\">bindings\/gi\/RB-3.0.gir<\/a>.<\/p>\n<p>The process to generate the docs from the .gir files was reasonably straight forward.  The only issue has to do with RB-3.0.gir &#8220;including&#8221; MPID-3.0.gir and the tool&#8217;s search path.  I used a kludgy method to allow <code>g-ir-doc-tool<\/code> to locate MPID-3.0.gir that I&#8217;m not especially proud of, but it got done.  The following commands generate .page output from the .gir files, then turn the .page output into .html.  I&#8217;m leaving in the error output and my solution to trying to find MPID-3.0.gir file for posterity<\/p>\n<pre class=\"brush: plain; title: ; notranslate\" title=\"\">\r\n$ cd ~\/swap\/rhythmbox\/rhythmbox-2.97\/bindings\/gi\r\n$ mkdir ~\/swap\/rhythmbox\/binding-docs\r\n$ g-ir-doc-tool --language Python -o ~\/swap\/rhythmbox\/binding-docs\/ .\/RB-3.0.gir \r\nCouldn't find include 'MPID-3.0.gir' (search path: ['gir-1.0', '\/usr\/share\/gir-1.0', '\/usr\/share\/gir-1.0', '\/usr\/share\/gir-1.0'])\r\n$ mkdir gir-1.0\r\n$ ln -s ..\/MPID-3.0.gir gir-1.0\/\r\n$ g-ir-doc-tool --language Python -o ~\/swap\/rhythmbox\/binding-docs\/ .\/RB-3.0.gir \r\n$ cd ~\/swap\/rhythmbox\/binding-docs\r\n$ \/bin\/ls -1 | wc -l\r\n1169\r\n$ yelp-build html .\r\n$ \/bin\/ls -1 | wc -l\r\n2345\r\n<\/pre>\n<p>There&#8217;s a <a href=\"http:\/\/www.jetmore.org\/john\/misc\/rb\/rb297-python-bindings.tar.gz\">tarball<\/a> of that output, and it can also be <a href=\"http:\/\/www.jetmore.org\/john\/misc\/rb\/rb297-python-bindings\/\">browsed directly<\/a>.  To complete the loop, here&#8217;s the page describing the <a href=\"http:\/\/www.jetmore.org\/john\/misc\/rb\/rb297-python-bindings\/RB.DisplayPageGroup.get_by_id.html\">RB.DisplayPageGroup.get_by_id()<\/a>.  I wish this form of the documentation would retain C function that&#8217;s being called on the backend (that info is in the .gir file), but it&#8217;s better than nothing.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I have an itch I want to scratch in Rhythmbox, and I&#8217;ve been looking at the Python bindings for writing plugins. It&#8217;s clear that you can do a lot of stuff, but there is no documentation specific to the Python &hellip; <a href=\"https:\/\/www.jetmore.org\/john\/blog\/2012\/07\/rhythmbox-python-bindings-documentation\/\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[5],"tags":[8,14],"_links":{"self":[{"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/posts\/806"}],"collection":[{"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/comments?post=806"}],"version-history":[{"count":9,"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/posts\/806\/revisions"}],"predecessor-version":[{"id":813,"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/posts\/806\/revisions\/813"}],"wp:attachment":[{"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/media?parent=806"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/categories?post=806"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.jetmore.org\/john\/blog\/wp-json\/wp\/v2\/tags?post=806"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}