Using grav for api documentation

Archive
1

Has anybody used grav for documenting APIs? I’m on a project that wants to produce a manual which has a hybrid menu of normal menu items with an api section, as done with readme.io at http://docs.embed.ly/docs/embedly-api, as in the following screenshot:

Embedly_api_docs

The main thing is to be able to recreate the nice coloured representation of the GET/PUT/POST endpoints in the menu.

Within the API sections themselves, I would also want to be able to display example code in tabbed boxes that enable switching languages, as in the following screenshot:

Embedly_api_docs_code_example

Has anybody attempted something similar? Or would somebody suggest a recommended approach for tackling this? Could it be done with some minor adjustments to RTFM?

2

The RTFM skeleton might be perfect for your needs.: https://github.com/getgrav/grav-skeleton-rtfm-site
it provides tabbed code boxes and is totally similar to what is used for Grav’s documentation section: www.learn.getgrav.org

3

I have used RTFM in its basic state for some ‘traditional’ manuals.
How do I activate the tabbed code boxes?
Would you know how I might adjust the display of APIs in the menu so that they are different to normal page items?

4

Never tried RTFM skeleton, but a look at the source code seems to indicate that

<div class="tabs-wrapper ui-theme-badges top-left">
    <ul class="tabs-nav">
                    <li class="current"><a href="#36ccda18f50" rel="tab">Markdown</a></li>
                    <li ><a href="#36ccda18f51" rel="tab">Twig</a></li>
                    <li ><a href="#36ccda18f52" rel="tab">HTML Code</a></li>
        </ul>
    <div class="tabs">
            <div class="tab" id="36ccda18f50">
<pre><code>![Some ALT text](sample-image.jpg "My title") {.myclass}</code></pre>
</div>
            <div class="tab" id="36ccda18f51">

<pre><code>{{ page.media['sample-image.jpg'].html('My title', 'Some ALT text', 'myclass') }}</code></pre>

</div>
            <div class="tab" id="36ccda18f52">
<pre><code><img title="My title" alt="some ALT text" class="myclass" src="/images/0/3/0/0/9/0300931b1b21ad420cf65a37c4089bc68e306a36-s ample-image.jpeg" /></code></pre>
</div> 
        </div>
</div>

will generate appropriate tabbed code boxes.
It’s probably available with shortcodes, or if it is not, you can probably make your own! hope it helps!

5

Thanks I’ll try and work with that! If anybody could help re the api menu items, that would be brilliant :slight_smile:

6

Why not use your own icon, and add it to, for example, icomoon ?

7

The issue with the menu is that I would need to have conditionals to switch to whatever solution (icomoon, fontawesome or just css) I use for an API menu item.
I have a very, very ugly semi-solution in that I have changed the colour of the font in the frontmatter:

title: <span style="color:red">GET </span>Client Initialization
taxonomy:
    category: docs

Which gives me the following:

Api_menu_pic

I would be able to adjust the css to make an api menu item, but I wouldn’t know how to introduce a conditional to implement it

8

I have achieved the tabbed code box functionality very easily by using the shortcodes-ui plugin https://github.com/getgrav/grav-plugin-shortcode-ui
Very easy, just a 5 minute install and go!

9

good job!