redaxmedia/tocgen

Generate table of contents from CSS and Javascript files

Installs: 9 057

Dependents: 3

Stars: 4

Watchers: 1

Forks: 2

Language: PHP

4.0.2 2014-09-08 15:48 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 Repo Size Latest Stable Version Total Downloads License

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.0.2"
    }
}

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.

Changelog

4.0.2

  • Color support for ansicon and cygwin

4.0.1

  • Fix typo in --quiet option
  • Coding styles for PHP

4.0.0

  • Switched from Windows to Unix EOL
  • Method _scanTarget was replace with the native DirectoryIterator
  • Introduced vendor/bin/tocgen.sh that redirects to vendor/redaxmedia/tocgen/cli.php
  • Recursively replace default .tocgen with your .tocgen file