Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

tools to mirror docs #1446

Open
yocontra opened this issue Dec 22, 2015 · 10 comments
Open

tools to mirror docs #1446

yocontra opened this issue Dec 22, 2015 · 10 comments

Comments

@yocontra
Copy link
Member

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

@yocontra yocontra added this to the gulp 4 milestone Dec 22, 2015
@yocontra yocontra assigned yocontra and unassigned yocontra Dec 22, 2015
@phated
Copy link
Member

phated commented Dec 22, 2015

@contra the gulp 3.9 cli is still matching those docs

@phated phated mentioned this issue Dec 23, 2015
5 tasks
@phated phated changed the title mirror docs Tool to mirror docs Apr 5, 2016
@phated phated mentioned this issue Apr 5, 2016
6 tasks
@phated
Copy link
Member

phated commented Apr 5, 2016

This can be a gitbook plugin

@phated phated changed the title Tool to mirror docs Gitbook plugin to mirror docs Apr 5, 2016
@jonschlinkert
Copy link

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
Copy link
Member

phated commented Apr 11, 2016

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
Copy link

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
Copy link
Member

phated commented Apr 12, 2016

@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
Copy link

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.

@phated phated modified the milestones: gulp 4 - next tag, gulp 4 - latest tag Jun 28, 2016
@phated phated changed the title Gitbook plugin to mirror docs tools to mirror docs Apr 17, 2018
@janiceilene
Copy link
Member

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

@phated
Copy link
Member

phated commented Feb 7, 2019

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

@janiceilene
Copy link
Member

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.

@phated phated removed this from the gulp 4 documentation milestone Feb 8, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants