Build offline documentation viewer app using Yelp

Applications
1

Hey,

I want to build an offline documentation app for which I already have my content in markdown format. I want to make it available in Linux app which users can read without internet access.

For the same, I’ve converted markdowns to HTML to display them in a viewer app using Yelp. But I don’t know where to start with Yelp to view my HTML contents. Is there a guide to getting started with Yelp and building your own doc viewer app like GNOME Help.

2

Not an expert on this, but what I would do:

  1. Read Yelp to check what format would be more convenient for using yelp with my content.
  2. Try to build some very simple document in that format, e.g. Ten Minute Tour, and test it from CLI with the yelp.
  3. Then play with https://developer.gnome.org/libyelp/3.26/ and see If I can make it load my sample content.

Then evaluate if this is the right approach for my app.

1 Like
3

Thanks for that. Now I think GNOME markdown viewer would be the best option to view my docs as they’re already in markdown format.

4

yelp supports processing Mallard and DocBook XML source files. If you convert Markdown into HTML, you can just a web browser to view them, no need for yelp I think.

5

For viewing documentation, there is Devhelp. It can read HTML documentation stored in gtk-doc/html directory under $XDG_DATA_DIRS (e.g. /usr/share, ~/.local/share), as long as you have an .devhelp2 index.

For example, you would have /usr/local/share/gtk-doc/html/foo, which would contain the HTML files and also foo.devhelp2. Here is a trimmed down devhelp2 file from GTK 3:

<book xmlns="http://www.devhelp.net/book" title="Foo Reference Manual" link="index.html" author="" name="foo" version="2" language="c" online="https://developer.gnome.org/foo/">
  <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.5"/>
        <sub name="Packing" link="ch01s02.html"/>
        <sub name="Building user interfaces" link="ch01s03.html"/>
        <sub name="Building applications" link="ch01s04.html">
          <sub name="A trivial application" link="ch01s04.html#id-1.2.3.12.5"/>
          <sub name="Populating the window" link="ch01s04.html#id-1.2.3.12.6"/>
        </sub>
        <sub name="Custom Drawing" link="ch01s05.html"/>
      </sub>
      <sub name="Mailing lists and bug reports" link="gtk-resources.html"/>
      <sub name="Common Questions" link="gtk-question-index.html"/>
      <sub name="The GTK+ Drawing Model" link="chap-drawing-model.html"/>
      <sub name="The GTK+ Input and Event Handling Model" link="chap-input-handling.html"/>
    </sub>
    <sub name="Glossary" link="glossary.html"/>
    <sub name="Index of all symbols" link="api-index-full.html"/>
    <sub name="Annotation Glossary" link="annotation-glossary.html"/>
  </chapters>
  <functions>
    <keyword type="typedef" name="GtkAllocation" link="GtkWidget.html#GtkAllocation"/>
    <keyword type="property" name="The “screen” property" link="GtkStyleContext.html#GtkStyleContext--screen"/>
    <keyword type="function" name="gtk_icon_info_is_symbolic ()" link="GtkIconTheme.html#gtk-icon-info-is-symbolic" since="3.12"/>
    <keyword type="struct" name="struct GtkIconThemeClass" link="GtkIconTheme.html#GtkIconThemeClass"/>
    <keyword type="macro" name="GTK_ICON_THEME_ERROR" link="GtkIconTheme.html#GTK-ICON-THEME-ERROR:CAPS"/>
    <keyword type="enum" name="enum GtkIconThemeError" link="GtkIconTheme.html#GtkIconThemeError"/>
    <keyword type="signal" name="The “changed” signal" link="GtkIconTheme.html#GtkIconTheme-changed"/>
    <keyword type="constant" name="GTK_ICON_THEME_FAILED" link="GtkIconTheme.html#GTK-ICON-THEME-FAILED:CAPS"/>
    <keyword type="member" name="GtkIconThemeClass.changed" link="GtkIconTheme.html#GtkIconThemeClass.changed"/>
  </functions>
</book>
1 Like
6

Sphinx can also generate the Devhelp index for you using GitHub - sphinx-doc/sphinxcontrib-devhelp but only the legacy devhelp1 version and I am not sure if that is still supported.

In the worst case, you can manually write a minimal index without any table of contents:

<book
  xmlns="http://www.devhelp.net/book"
  title="Foo Reference Manual"
  link="index.html"
  name="foo"
  version="2" />
1 Like
7

Hey, is it possible to use Yelp to display HTML files? because launching yelp with file URL displays “The URL can’t be shown.”

8

It should be possible, but I see that it doesn’t work with any HTML file. I think I tried in the past and it worked (but I’m not that sure…).

I’ve opened an issue on yelp tracker.

@shaunm can you help us to debug this?

9

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.