redaxmedia/tocgen

Generate table of contents from CSS and Javascript files

4.1.1 2016-01-04 11:37 UTC

README

Table of Contents Generator Generate table of contents from CSS and Javascript files

Generate table of contents from CSS and Javascript files.

Scrutinizer Code Quality Dependency Status Latest Stable Version Total Downloads License GitHub Stats

API

Send a POST request to api.php.

$_POST[1]:

Single file contents.

$_POST[2]:

Config from .tocgen file.

CLI

Run sh vendor/bin/tocgen.sh {path} {config} {options} from console. This bash is a shortcut that redirects to vendor/redaxmedia/tocgen/cli.php.

Example:

Walk templates recursively with your .tocgen file:

sh vendor/bin/tocgen.sh templates .tocgen --recursive

Path:

Single file or directory.

Config:

Load config from another .tocgen file.

Options:

--force, -f - Force table of contents generation

--recursive, -r - Walk target recursively

--lint, -l - Lint for errors (readonly)

--quiet, -q - Print nothing to console

Service

Website:

http://tocgen.net

API:

http://tocgen.net/api.php

Example:

A simple integration using jQuery's AJAX component:

$.ajax(
{
    url: 'api.php',
    type: 'post',
    data:
    {
        1: input.val(),
        2: config.val()
    },
    success: function (data)
    {
        output.val(data);
    }
});

Config

Configuration are stored inside .tocgen file:

{
    "eol": "\n",
    "toc":
    {
        "flag": "@tableofcontents",
        "start": "/**",
        "end": " */\n\n",
        "prefix": " * ",
        "delimiter": " *\n",
        "indent": "   ",
        "head": "\n * @tableofcontents\n *\n",
        "foot": ""
    },
    "section":
    {
        "flag": "@section",
        "start": "/*",
        "end": "*/",
        "delimiter": ".",
        "pattern": "/\\/\\*(.|[\n])*?\\*\\//"
    }
}

Foot with @since, @package and @author annotations:

"toc":
{
    "foot": " *\n * @since 1.0.0\n *\n * @package Your Project\n * @author Your Name\n"
}

Alternative pattern to handle sections with multiple lines:

"section":
{
    "pattern": "/\\/\\*([\\s\\S]*?)([\n])|\\*\\//"
}

Composer

How to register Tocgen inside composer.json:

{
    "require-dev":
    {
        "redaxmedia/tocgen": "4.1.1"
    }
}

Grunt

How to implement Tocgen into gruntfile.js using the grunt-shell extension:

/* config grunt */

grunt.initConfig(
{
    shell:
    {
        toc:
        {
            command: 'sh vendor/bin/tocgen.sh css && sh vendor/bin/tocgen.sh js',
        },
        toclint:
        {
            command: 'sh vendor/bin/tocgen.sh css -l && sh vendor/bin/tocgen.sh js -l',
        },
        options:
        {
            stdout: true,
            failOnError: true
        }
    }
}

/* load tasks */

grunt.loadNpmTasks('grunt-shell');

/* register tasks */

grunt.registerTask('toclint',
[
    'shell:toclint'
]);
grunt.registerTask('toc',
[
    'shell:toc'
]);

Task toclint returns exit on errors and works perfect with Travis CI and other continous integration tools.

Troubleshooting

Keep in mind that EOL inside your .tocgen file equals your IDE's setup and operation system. Otherwise Tocgen fails to detect existing table of contents and therefore generates a fresh one.