tools to mirror docs

[yocontra]

We should add a build script that pulls in the markdown docs from other projects

Example: Our CLI.md in this repo is out of date with https://github.com/gulpjs/gulp-cli/blob/master/docs/CLI.md

[phated]

@contra the gulp 3.9 cli is still matching those docs

[phated]

This can be a gitbook plugin

[jonschlinkert]

following up from https://twitter.com/BlaineBublitz/status/719612540636962816...

I think it might help to give more detail on the types of projects do you want to inline. Then based on the relationships between the projects, and how automated you want it to be, we can more easily come up with an idea of what needs to be accomplished.

For example, do you want docs for dependencies/core libs? gulp plugins, etc? Some thoughts/questions that come to mind that might help clarify what you'd like to achieve. Maybe none or all of these are relevant:

• do you want to just inline the docs from other repos or do you want to actually merge docs if possible?
• do you want to do things like automatically cross-reference inherited methods?
• we could also build up a context of urls to the docs, code and tests for dependencies, so links can be created in gulp docs using simple variables that will automatically update when urls change.

etc...

fwiw this concept in general is something @doowb and I are really interested in. we've spent thousands of hours on templating/markdown/documentation-related stuff b/c we see it as a huge productivity barrier in our space. so regardless of what you guys decide on I'm really curious/interested in the outcome.

[phated]

I was thinking that it would just take something like <!--- include isaacs/node-glob#master glob-primer ---> and it would pull the section https://github.com/isaacs/node-glob#glob-primer (not sure about with or without the header) from the glob docs and inline it below the comment. The comment would need to stay so they could be re-processed multiple times (maybe we would need a closing comment then too). One thing I noticed while looking into this is that 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 think it should only be a shallow inline, so each repo would have to include and process what it wants to inline.

@jonschlinkert let me know if that helps at all or if any of it is confusing. It is just a brain dump of my couple hours spent on this.

[jonschlinkert]

was thinking that it would just take something like <!--- include isaacs/node-glob#master glob-primer --->

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.

[phated]

@jonschlinkert great points, I'm definitely going to think about those things. I'd love to chat or screenshare about your ideas some time.

[jonschlinkert]

great, starting Tues. of next week my schedule will open up a bit. Let me know what works for you, I'd love to get your thoughts also.

[janiceilene]

@phated Is this still something we're thinking about doing?

[phated]

I desperately want it but it's a big programming thing instead of a docs thing. We could remove the tag, probably

[janiceilene]

Removed it from the docs project board, added it back to the general projects in Nice to have. I don't have permissions to change labels.