[epic] Documentation work #1595

Open
phated opened this Issue Apr 5, 2016 · 15 comments

Projects

None yet

4 participants

@phated
Member
phated commented Apr 5, 2016 edited

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 (initial structure in the new-docs branch)
  • 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
  • Gitbook theme that matches the website (ref gulpjs/gulpjs.github.io#31)
  • Tooling or gitbook plugin for inlining docs (makes other items easier but not mandatory - ref #1446)

Ref #1465 (comment)

@phated phated added this to the gulp 4 milestone Apr 5, 2016
@phated
Member
phated commented Apr 5, 2016

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
Member
phated commented Apr 5, 2016

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
Member
phated commented Apr 5, 2016

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
Member
phated commented Apr 5, 2016

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

@phated
Member
phated commented Apr 5, 2016

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

@phated
Member
phated commented Apr 5, 2016

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

@wesbos
wesbos commented Apr 10, 2016

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

@phated
Member
phated commented Apr 10, 2016

@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
Member
phated commented Apr 22, 2016

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.

@phated phated referenced this issue in gulpjs/gulpjs.github.io Apr 27, 2016
Open

Gitbook theme for the gulp website #31

@phated
Member
phated commented Apr 30, 2016

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.

@phated phated changed the title from Convert docs to gitbook to [epic] Convert docs to gitbook May 17, 2016
@phated
Member
phated commented May 17, 2016

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 phated changed the title from [epic] Convert docs to gitbook to [epic] Documentation work May 28, 2016
@erikkemperman

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

@phated
Member
phated commented Jun 13, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment