[epic] Documentation work

[phated]

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:

• Decide on and finalize a folder structure
• Update docs to match completed docs in other modules (vinyl-fs, vinyl, undertaker, etc)
• Finish docs in other modules that need completion (bach)
• Cleanup recipes, make sure they work with 4.0 and are consistent with each other (superseded by [Docs] Recipes #2164)
• Docusaurus setup for the website (ref Docusaurus theme for the gulp website gulpjs.github.io#31)
• Tooling for inlining docs (makes other items easier but not mandatory - ref tools to mirror docs #1446)

Ref #1465 (comment)

[phated]

We will need a gitbook plugin that fetches a markdown file from github and clips out a section based on a header. Ref #1446

[phated]

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

[phated]

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

[phated]

Example directory structure at https://github.com/reactjs/redux/tree/master/docs

[phated]

We might also want to look into https://github.com/GitbookIO/plugin-versions to support old or future versions of the docs.

[phated]

Documentation for custom theming: http://toolchain.gitbook.com/themes/

[wesbos]

I can't take this 100% on but I'd love to help with the docs.

[phated]

@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?

[herrbischoff]

I'd also like to help with docs.

[phated]

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.

[herrbischoff]

Alright, just let me know what exactly I should do and I'll start.