Neutrinos Peludos Magnéticos

    snippet-collector
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.6 • Public • Published

    About

    snippet-collector is a simple utility that lets you extract out example snippets from your source and test files, so that they can be reused in your docs. That way, your docs never go out of sync with the source and you can ensure that your examples are covered by your test suite.

    Installation

    Ensure node and npm are installed. Only latest stable version is supported at this point.

    As local dependency

    npm install --save-dev snippet-collector
    /```
     
    Add a script entry in package.json:
     
    ```json
    {
        "scripts"{
            "snippets:collect""snippet-collector --files ./src/**/*.js --output ./generated/snippets.json"
        }
    }

    As global dependency (Not recommended)

    npm install -g snippet-collector

    A sudo may be required, depending on how node installation is configured.

    Usage

    Annotating the source/test files with snippet directives

    Snippets can be marked by @snippet:start and @snippet:end directives.

    // @snippet:start usage
    const foo = Foo();
    foo.bar();
    // @snippet:end

    It is possible to have composite snippets spread across multiple-files - They will be concatenated in the specified order (which is mandatory if there are multiple snippets of the same name).

    // @snippet:start usage:0
    import Foo from "foo-lib"
    // @snippet:end
     
    // @snippet:start usage:1
    const foo = Foo();
    foo.bar();
    // @snippet:end

    The order indices must start from 0 and must be contiguous. Otherwise, an error will be thrown.

    As CLI:

    snippet-collector --files ./src/**/*.js --output ./generated/snippets.json

    Your documentation generator can use the extracted json. The structure of json looks like this:

    {
        "usage": {
            "name": "usage",
            "content": "import Foo from \"foo-lib\";\rconst foo = Foo();\rfoo.bar();\r"
        }
    }

    Entries are keyed by snippet name and have a content property containing the combined snippet text.

    As Node library

    It is also possible to use snippet-collector as a node library:

    const {processSnippets} = require('snippet-collector');
     
    processSnippets({
        globPatterns: './src/**/*.js',
        outputFile: './generated/snippets.json'
    });

    Or alternatively, you can skip the generation and just get the extracted collection of snippets:

    const {collectSnippets} = require('snippet-collector');
     
    collectSnippets({
        globPatterns: './src/**/*.js'
    }).then((snippets) => {
        console.log('snippets =>', snippets);
    });

    This returns a promise that resolves to a javascript object of same structure as above.

    Contributing

    Suggestions, bug reports as well as PRs are welcome. However, it is advisable that any suggestion that significantly alters the scope of the project be discussed first.

    License

    MIT

    Keywords

    Install

    npm i snippet-collector

    DownloadsWeekly Downloads

    0

    Version

    1.0.6

    License

    MIT

    Unpacked Size

    20.5 kB

    Total Files

    14

    Last publish

    Collaborators

    • lorefnon