DASH DOCSET BUILDER

That shit creates Dash Docsets for you. Of course you still need to declare some stuff in your own class. That shit doesn't read minds yet. See more below.

DASH IS LOVE

When coding with Sublime + Chrome in Split View, Dash is the savior ❤️

HOW TO USE (ALSO KNOWN AS USAGE)

Install the awesome tool (ambiguous meaning)

composer require godbout/dash-docset-builder

Generate your pretty Docset class

dash-docset new my-pretty-docset

You now have a beautiful MyPrettyDocset class that you're gonna have to edit. See below.

Edit your pretty Docset class

Your Docset Class has to extend the BaseDocset class that implements the Docset interface. That allows the Builder to make your Docset with just a little configuration.

Your Docset Class has to define the following constants:

// To generate the docset filename
public const CODE = 'tailwindcss';
// What name will show up in Dash
public const NAME = 'Tailwind CSS';
// Where to download the doc from
public const URL = 'tailwindcss.com';
// What page should the docset show by default
public const INDEX = 'installation.html';
// A link to try the service/app, if any
public const PLAYGROUND = 'https://codesandbox.io/s/github/lbogdan/tailwindcss-playground';
// Where to grab the icon in 16x16 res
public const ICON_16 = 'favicon-16x16.png';
// Where to grab the icon in 32x32 res
public const ICON_32 = 'favicon-32x32.png';
// List of external domains where images or other files have to
// be downloaded, if not from URL defined above
public const EXTERNAL_DOMAINS = [
    'refactoring-ui.nyc3.cdn.digitaloceanspaces.com',
    'jsdelivr.net',
    'code.jquery.com',
    'rsms.me',
    'googleapis.com',
];

Then there are two mandatory methods to define:

/**
 * This method is responsible for generating the Dash Table of Contents
 *
 * For each HTML file of your downloaded doc, this method will be called.
 * You have to parse the file (how you want) and return a collection of
 * entries. See Docsets in
 * https://github.com/godbout/dash-docsets/tree/master/app/Docsets
 * for examples.
 */
public function entries(string $file): Collection
{
    $crawler = HtmlPageCrawler::create(Storage::get($file));

    $entries = collect();
    $entries = $this->generateEntries($crawler, $file);

    return $entries;
}

/**
 * This method is responsible for formatting the doc for Dash
 *
 * For each HTML file of your downloaded doc, this method will be called.
 * You have to update the content of the file and return that content.
 * The file is passed as argument rather than its content because sometimes
 * the file name is the only way you have to generate the Dash Online Redirection.
 * See Docsets in 
 * https://github.com/godbout/dash-docsets/tree/master/app/Docsets
 * for examples.
 */
public function format(string $file): string
{
    $crawler = HtmlPageCrawler::create(Storage::get($file));

    $this->modifyHtml($crawler, $file);

    return $crawler->saveHTML();
}

The Builder provides a generic way to download your Docset docs. It'll use a sitemap.xml if found, else it'll go through your Docset index. If you need to provide your own way of downloading your docs, you can define a grab() method in your Docset. The Builder will catch it and use your custom method instead.

public function grab(): bool
{
    system(
        "wget doc.tiki.org/All-the-Documentation \
            --mirror \
            -e robots=off \
            --header 'Cookie: javascript_enabled_detect=true' \
            --reject-regex='/Plugins-|Plugins\.html|fullscreen=|PDF\.js|tikiversion=|comzone=|structure=|wp_files_sort_mode[0-9]=|offset=|\?refresh|\?session_filters|\?sort_mode' \
            --accept-regex='/Plugin|/LIST|Tiki_org_family|\.css|\.js|\.jpg|\.png|\.gif|\.svg|\.ico|\.webmanifest' \
            --page-requisites \
            --adjust-extension \
            --convert-links \
            --span-hosts \
            --domains={$this->externalDomains()} \
            --directory-prefix=storage/{$this->downloadedDirectory()}",
        $result
    );

    return $result === 0;
}

Build your Docset

Once your class is set up, run:

dash-docset build my-pretty-docset

This will download the doc, package it into a .docset file, and create an archive—useful if you want to contribute it to Dash—in the storage folder.

ENJOY

Enjoy your new fresh Docset and maybe also share it with the community that would be nice kiss kiss: https://github.com/Kapeli/Dash-User-Contributions.

DOCSETS GENERATED WITH THIS BUILDER

Elderlies go first:

godbout / dash-docset-builder

readme