For gulp 4, we are going to be converting the documentation to gitbook and hosting on gulpjs.com.
The list of things that need to be done:
Ref #1465 (comment)
We will need a gitbook plugin that fetches a markdown file from github and clips out a section based on a header. Ref #1446
Should be able to put the book.json in the docs/ directory and use GITBOOK_DIR environment variable to point at that directory. This keeps the root of the project a bit more clean. Ref https://github.com/GitbookIO/gitbook-cli/blob/master/lib/config.js#L6
It looks like all gitbook filters are set to be async, a promise just needs to be returned. That should make it easy to implement the plugin that fetches docs from other projects. Ref https://github.com/GitbookIO/gitbook/blob/master/lib/template/index.js#L104-L114
Example directory structure at https://github.com/reactjs/redux/tree/master/docs
We might also want to look into https://github.com/GitbookIO/plugin-versions to support old or future versions of the docs.
Documentation for custom theming: http://toolchain.gitbook.com/themes/
I can't take this 100% on but I'd love to help with the docs.
@wesbos awesome! I started a branch at https://github.com/gulpjs/gulp/tree/new-docs but I don't like mirroring the docs in a .docs/ directory. I'm not sure of a better way to handle templating (which I think is needed to pull in external docs from libraries like vinyl-fs, node-glob, etc). Any thoughts?
I'd also like to help with docs.
In the short term, I think we should just inline docs by hand to the 4.0 branch. I'm not very happy with the new-docs branch.
Alright, just let me know what exactly I should do and I'll start.
I moved the .docs/ directory back to docs/ in the new-docs branch. Any improvements (structure, content, etc) are welcome. Best place to start is to look at the respective projects and see if their documentation is better (I've improved some of it) than what is currently in new-docs and update/improve it.
Renamed this "epic" and updated the main issue to have a list of things that need to get done. Will add stuff as it comes up.
@phated Maybe this is a moot question given this issue, but I just noticed that there are currently two CLI.md docs, one here and one over at gulp-cli. The latter one seems older / outdated (meld tells me the one here has additions that the gulp-cli one doesn't) but that's the one which is fed into marked-man...
@erikkemperman the CLI docs need to be pulled from gulp-cli master branch (either the readme or https://github.com/gulpjs/gulp-cli/blob/master/docs/CLI.md)