was thinking that it would just take something like 

There are couple of issues with this. The injecting part is pretty simple. we do this a lot with stuff like markdown-toc and inject-snippet.

But if we're parsing another document to create the snippet, it introduces lots of potential snags. Like relative links to other docs or sections in the same document. when headings that have code in them it makes them harder to work with or unusable. honestly this is just the surface. I've hit so many snags trying to do this.

I want to pull the entire API doc from https://github.com/gulpjs/vinyl-fs#srcglobs-options but the example uses fs.src instead of gulp.src so maybe there would need to be some sort of post-processing too, not sure.

I would love to settle on a solution for this. I've been trying to do this for probably the past two years. We've done it in a few ways that failed. Recently we tried using variables like <%= name %>.set() or something in our docs, which would render to verb.set(), app.set() etc. but it's horrible to maintain

For me, finding a workable solution to this is more than a nice-to-have. It would mean that we all spend more time programming, users and implementors learn how to use our libs faster and with greater depth, and it should cut down on issues that can be distracting to progress.

Anyway, when it comes to maintaining projects, IMHO nothing is as bad as having to re-write the same documentation on multiple projects. It's not even about duplicating efforts. It's about keeping the docs current and consistent. when docs are repeated on two libs, it's a virtual guarantee that one of them will be incorrect or outdated at any given time. If inlining docs is a build step, at least the docs will be as up-to-date as the last time you ran gulp or verb or whatever you use.

sorry, that's my brain dump. I have solutions to some of this that seem like they're going to work out well. if you're interested I can give more detail. maybe even do a screen share or something.

Uh oh!

tools to mirror docs #1446

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions