Re: Python Docs (was Re: Coordination for developer documentations)

[Frederic Peters <fpeters gnome org>]

Stefan Sauer wrote:

> On 03/08/2014 06:15 PM, Christoph Reiter wrote:
> > I've tried the devhelp export and it seemed to work quite well for the all
> > in one API docs. But I'm not sure how linking between different Sphinx
> > builds would work with devhelp. (but I have no idea how devhelp does it
> > with other sources either..)
> devhelp is basically the index.sgml (ignore the sgml extension, it is
> not) + prerendered html. devhelp does not do anything with the link in
> the html doc, except trying to follow them when one is clicked.

Indeed, the pages rendered by devhelp are HTML pages taken straight
from the filesystem, with no transformation at all.  As I wrote to
Giovanni earlier, it would certainly be possible to reuse YelpView,
to get support for Mallard files.

Next to the document view, for the tree of documents and the keyword
search, devhelp requires a file in its own '.devhelp2' xml format;
it's actually quite simple, it goes like this:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<book xmlns="http://www.devhelp.net/book"; title="GTK+ 3 Reference Manual"
      link="index.html" author="" name="gtk3" version="2" language="c">
  <chapters>
    <sub name="GTK+ Overview" link="gtk.html">
      <sub name="Getting Started with GTK+" link="gtk-getting-started.html">
        <sub name="Basics" link="gtk-getting-started.html#id-1.2.3.3"/>
        ...
  </chapters>
  <functions>
    <!-- functions -->
    <keyword type="function" name="gtk_dialog_run()"
             link="GtkDialog.html#gtk-dialog-run"/>
    !-- but also other types
    <keyword type="struct" name="struct GtkApplicationClass"
             link="GtkApplication.html#GtkApplicationClass"/>
    <!-- possibility to mention when it got added -->
    <keyword type="enum" name="enum GtkApplicationInhibitFlags"
             link="GtkApplication.html#GtkApplicationInhibitFlags" since="3.4"/>
    <!-- and also when it got deprecated -->
    <keyword type="function" name="gtk_dialog_set_alternative_button_order()"
             link="GtkDialog.html#gtk-dialog-set-alternative-button-order"
             deprecated="3.10: Deprecated" since="2.6"/>


        Fred