jamesramsay / hercule Goto Github PK

First off, very helpful library, appreciate the hard work.

Working on documenting a large api using apiary and using hercule to handle various includes to make things a bit more manageable. I've written a simple gulp watcher to monitor changes and dump everything into the main .apib file, and all that works great. The only problem I've found is that when I screw up a file path hercule causes my gulp watcher to hang. I will get an error like 'Error: File (badfilename.md) not found.', and all execution stops. I can manually kill the task, fix the error and restart it, but that's not what I'm looking for. I don't claim to be a gulp expert, but I've tried various ways of error handling, and none have managed to catch the error.

I have found one solution to the problem. If I change the default return statement in readFile() (utils.js) from return null to return '' (empty string), then I will still get the error (which is good), but the task will continue and I can address my mistake without restarting.

So, am I missing something? Is there a best practice for this kind of error handling? Will this modification break something else in hercule that I haven't spotted yet?

Currently the npm version must be bumped manually for every release. Ideally a script should be used to increment, commit, tag and push to master.

• master is currently protected which will need to be changed.

Appears to be due to posttest not being run because npm test isn't being called due to the build matrix setup.

Links currently must be relative file links. It could be interesting to reference remote files, but not sure what instances this would be particularly useful in...

Currently linting requires an issue references. This requirement should be removed.

A number of dev dependencies have fallen behind:

• babel (minor)
• nock (minor)
• eslint-config-airbnb (major)

https://github.com/sindresorhus/eslint-plugin-ava

Refer to test case using fixtures/test-extend/fox.md

The quick brown fox jumps over the lazy dog\n .\n

Ideally it should output:

The quick brown fox jumps over the lazy dog.\n

Travis should run tests against current versions (0.10, 0.12, 4, and 5)

Note that sync API relies on > node 0.12, and sync tests will need to be skipped.

• Multiple level file transclusions #88
• Multiple level http transclusions #121

Currently log output is defaulting to stderr, not stdout preventing bunyan from being able to parse output.

Any chance this could run in the browser one day?

It will be very useful for transcluding many (dynamically created?) files from dir.

Override path's are being treated as relative to the location of the ultimate transclusion rather than override source location.

Using the syntax:

:[link to something](file.md#section-6)

Yet to be determined, what h (#) levels to support? From h1 to h3 or down to h6? How often does one need to include part of a document but not all of it?

This utility is high modular and could be easily isolated into a separate node module.

https://github.com/codemix/babel-plugin-typecheck

According to the examples the below should be a valid link:

:[Example here](example.md)

However when I run it...
Running "hercule:docs" (hercule) task
Fatal error: Expected "]" or [a-zA-Z0-9] but " " found.

When I get rid of the white space the below works:

:[ExampleHere](example.md)

https://github.com/gajus/gitdown does all of the things as Hercule (transclusion) and more.

This is not meant as an advertisement and more of a "lets combine the forces".

Hi there,

I'm trying to allow authors to transclude with a simpler link syntax in the same way that using permalinks in a static site generator allows to create links and forego the extensions (in an SSG by renaming something.html to something/index.html which means that [my permalink](something) works which is a more "human" link. I'd like to be able to do :[my permatransclusion](something) and have hercules try something and if asked to (with some kind of config flag I guess) then try to resolve something.md.

Would this be possible?

Cheers,

Jun

When peg crashes, no useful information is provided.

/Users/james.ramsay/Development/buyer-api/node_modules/hercule/lib/transclude-parser.js:907
      throw peg$buildException(
            ^
SyntaxError: Expected " ", [^ ()\"], [a-zA-Z0-9] or end of input but "\"" found.

This was triggered by a typo (bar: appears twice):

:[example][foo.md bar:bar:"fizz buzz"]

There seems to be some dependency on blanket for non dev installs.
After a 'npm install -g hercule', running hercule throws:

module.js:338
throw err;
^
Error: Cannot find module 'blanket'
at Function.Module._resolveFilename (module.js:336:15)
at Function.Module._load (module.js:278:25)
at Module.require (module.js:365:17)
at require (module.js:384:17)
at Object. (/usr/local/lib/node_modules/hercule/lib/main.js:5:13)
at Object. (/usr/local/lib/node_modules/hercule/lib/main.js:80:4)
at Module._compile (module.js:460:26)
at Object.Module._extensions..js (module.js:478:10)
at Module.load (module.js:355:32)
at Function.Module._load (module.js:310:12)

An init script will make it easier for cloners to make alterations and have pre-commit and commit-msg hooks run as expected.

To replicate:

index.md
foo/file1.md
foo/file2.md

index.md transcludes foo/file1.md, file1.md transcludes file2.md but file2 is incorrectly being searched for in the root rather than folder foo.

• Test for when file handling warning is shown
• Test for when http handling warning is shown

Reporters:

• tree
• basic
• json (used by sync API and pushes all log messages onto stderr for spawnSync to capture)

File test.md sets a string placeholder to "venues":

:[](blueprints/venues.md resource:"venues")

File blueprints/venues.md

# Group Venues

## Add venues [/venues]

:[](post.md attributes:"Venue" description:"This and that")

File post.md is expected to just print the resource placeholder

:[](resource)

Now, transcluding test.md gives me the following error:

$ hercule --verbose doc/test.md -o doc/out/APIv2local.apib
Transcluding file... doc/test.md
Links found: 1
Transcluding: doc/blueprints/venues.md (file) into doc/blueprints/venues.md
Links found: 1
Transcluding: doc/blueprints/post.md (file) into doc/blueprints/post.md
Links found: 1
Error: File (doc/blueprints/resource) not found.
Transcluding: doc/blueprints/resource (file) into doc/blueprints/resource
Links found: 0

If I remove the placeholders in the second file, then all is well.
It seems to me, that subsequently defined placeholders will clear all previously defined placeholder during the transclusion, or am I just doing it wrong?

If this is a chosen or known limitation, then the possibility to merge placeholders would be a really nice feature.

When working on a large API Blueprint document spread over multiple files, it would be useful for linting (e.g. https://github.com/zdne/linter-api-blueprint) to provide the feedback based on the compiled output rather on each unit.

In order for this to be possible:

• source map output from Hercule
• linter would need to detect source map, identify which files are referenced from it so that they are linted based on compiled output rather than source

Is there possible to extract html - String from Body description

+Body

{
   field1: 'Value1'
   html: '<HEAD></HEAD><BODY></BODY>'
}

I don't need to extract whole body to JSON file, only HTML needed.

Much of the mock data is a little misleading to the internals of Hercule.

es.map is only being used in a single location and can be simply replaced with through2 which is used through out the project.

Passing a placeholder via some included files will be very userful and makes my project less complicated.

first.md

:[](second.md placeholder:"John")

second.md

Hello :[name](placeholder)
:[](third.md placeholder:placeholder)

third.md

How are you, :[name](placeholder)?

Being able to generate a list of paths to watch, allows live preview capabilities.

Not sure if it's intended to be supported or not (if not consider this a feature request), but would be good to transclude included files; i.e.

 file1.md:
 I want to transclude [ThisOne](file2.md)

file2.md:
And I'm so DRY and lazy I'd like to transclude [ThisOneHere](file3.md)

file3.md:
Must I do everything?

Just did a clean global install of Hercule. First attempt to run it:

module.js:338
    throw err;
          ^
Error: Cannot find module 'blanket'
    at Function.Module._resolveFilename (module.js:336:15)
    at Function.Module._load (module.js:278:25)
    at Module.require (module.js:365:17)
    at require (module.js:384:17)
    at Object.<anonymous> (/usr/local/lib/node_modules/hercule/lib/main.js:5:13)
    at Object.<anonymous> (/usr/local/lib/node_modules/hercule/lib/main.js:80:4)
    at Module._compile (module.js:460:26)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)

Mac OS X Yosemite

It did give me these errors upon installation though:

$ sudo npm install -g hercule
/usr/local/bin/hercule -> /usr/local/lib/node_modules/hercule/bin/transclude
npm WARN unmet dependency /usr/local/lib/node_modules/bower/node_modules/tar-fs/node_modules/tar-stream/node_modules/bl requires readable-stream@'~1.0.26' but will load
npm WARN unmet dependency /usr/local/lib/node_modules/bower/node_modules/tar-fs/node_modules/tar-stream/node_modules/readable-stream,
npm WARN unmet dependency which is version 1.0.33-1
[email protected] /usr/local/lib/node_modules/hercule
├── [email protected]
├── [email protected]
├── [email protected]
└── [email protected] ([email protected])

Articles

• https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
• http://365git.tumblr.com/post/3308646748/writing-git-commit-messages
• http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Examples

• http://eslint.org/docs/developer-guide/contributing/pull-requests

Commit message checking:

• https://github.com/eslint/eslint/blob/master/Makefile.js#L927
• https://raw.githubusercontent.com/angular/angular.js/291d7c467fba51a9cb89cbeee62202d51fe64b09/validate-commit-msg.js

I'd really like a synchronous API for hercule. It's pretty simple to make a synchronous call become asynchronous—just wrap it in a setImmediate or similar—but it's rather hard to go the other direction. As best as I can tell the only thing keeping it synchronous is support for transcluding from an HTTP address. Would you be willing to make (or accept a pull request for) a version of hercule that works synchronously, dropping support for HTTP transcludes?

We are using hercule for generating our finished API Blueprint. By now a lot of thought and try/error went into how to best create DRY blueprints? and one thing that turned out to be very helpful were default values. So we have this atomic MSON objects, from whereon we generate (thanks to hercule) more complex MSON objects (which keeps everything super DRY). Now the problem is, that an MSON object might have slightly different settings based on where it gets used e.g. response vs. request (which makes the approach only super DRY, but not as DRY and flexible as possible). A quick example.

[file: title.md]
- title: None (string, required)

    The title

So in our response this atomic MSON object would be quite alright, but in our request we face the problem, that it might not be required, therefore we would have to repeat ourselves all over again. But support for default values could solve the problem.

[file: title.md]
- title: None (string, :[Presence Placeholder](presence || "required"))

    The title

Now we can reuse this atomic MSON object wherever we need it.

## Get Product Response Attribute

:[Product Title](title.md)

## Create Product Request Attribute

:[Product Title](title.md presence:"optional")

This also comes in handy for different sample values for different requests/responses and testing the blueprint with Dredd.

Now, if that is too abstract and a bigger picture is missing you can check out our example API Blueprint that documents and outlines how we use hercule to create DRY API Blueprints.

Also, I already wrote the code for providing support for default values. You can find the fork here.

I am not sure though if that is something that proves valuable to you, yet. Maybe you already have some thoughts about the support for default/fallback values? I am just curious what you think about it and if you could imagine to integrate something like this into the project.

See: istanbuljs/nyc@c6a23b9

Tests should ad here to coding style too.

The RegExp tokenizer solves a more generic problem and should be made a separate node module.

Promises are a key part of ES2015 and should be supported by Hercule.

Pre-requisite to #166

In the Readme (https://github.com/jamesramsay/hercule#usage), there is an example describing how to use this library. This example does not currently work as described in node 4.2.1.

It specifically errors at the very start of transcludeStringSync in lib/hercule.js

function transcludeStringSync(input, _ref2, log) {
  var relativePath = _ref2.relativePath;

The example in the Readme does not provide a second parameter, so in the above function _ref2 does not exist, and accessing relativePath on _ref2 throws an error.

This is fixed by providing an object as the second parameter, with a relativePath property.

var hercule = require('hercule');

var output = hercule.transcludeStringSync("# Title\n\n:[abstract](abstract.md)", {
    relativePath: __dirname
});

console.log(output);

Which side of this problem do you think needs to be fixed? Is relativePath a required option? Or should the function declare that field optional?