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

[epic] Documentation work #1595

Closed
4 of 6 tasks
phated opened this issue Apr 5, 2016 · 28 comments
Closed
4 of 6 tasks

[epic] Documentation work #1595

phated opened this issue Apr 5, 2016 · 28 comments

Comments

@phated
Copy link
Member

phated commented Apr 5, 2016

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)

@phated phated added this to the gulp 4 milestone Apr 5, 2016
@phated
Copy link
Member Author

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

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

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

phated commented Apr 5, 2016

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

@phated
Copy link
Member Author

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

phated commented Apr 5, 2016

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

@wesbos
Copy link

wesbos commented Apr 10, 2016

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

@phated
Copy link
Member Author

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

I'd also like to help with docs.

@phated
Copy link
Member Author

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

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

@phated
Copy link
Member Author

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 Convert docs to gitbook [epic] Convert docs to gitbook May 17, 2016
@phated
Copy link
Member Author

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 [epic] Convert docs to gitbook [epic] Documentation work May 28, 2016
@erikkemperman
Copy link
Member

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

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)

@phated phated modified the milestones: gulp 4 - next tag, gulp 4 - latest tag Jun 28, 2016
@revelt
Copy link

revelt commented Feb 2, 2017

Also, we should add instructions to v.4 docs how to actually install gulp v.4, because currently npm install --save-dev gulp will install v.3.9.1, yet this instruction is currently given on "https://github.com/gulpjs/gulp/blob/4.0/docs/README.md > Getting Started"

@salmanwaheed
Copy link

salmanwaheed commented Feb 2, 2017 via email

@phated
Copy link
Member Author

phated commented Oct 23, 2017

I think we can use something like https://github.com/jonschlinkert/section-matter to help define where information for each section comes from.

@jonschlinkert
Copy link

to help define where information for each section comes from.

Oh interesting... let me know if you think of other ways to delimit the sections. I wasn't very creative with the defaults. I'd be happy to implement something more flexible if necessary. Ideas welcome.

@avegancafe
Copy link

Is there anything that we can do to help out with the doc work? I saw this comment, not sure if there's anything we as a community can be doing to help push it across the finish line though

@phated
Copy link
Member Author

phated commented Jan 2, 2018

@kyleholzinger basically, all of the documentation needs to be rewritten. As I was finishing up all our dependencies (and sub-dependencies), I made sure to document them completely, so the effort is to compile all the docs and improve them for the "gulp context".

I'd love to have an automated way to pull docs from those repos but I don't see a clean way for that to happen, so we'll probably just get this done manually.

I also believe that the recipes need to be cleaned up (some are very complex and people seem to just copy them verbatim) and more recipes should probably be created for new gulp 4 features.

@phated
Copy link
Member Author

phated commented Jan 2, 2018

I'd also like to have an official migration guide but that's tracked in #861

@avegancafe
Copy link

avegancafe commented Jan 2, 2018

@phated you could probably write a little script to pull all the readme's from all our deps and sub-debs though not sure if there's an easy way to know which ones to pull (it'd be a lot of readme's if we did all of them haha). Is there a list of any of the ones that you documented publically available? Sounds like an easy win

@phated
Copy link
Member Author

phated commented Jan 29, 2018

@kyleholzinger it's going to be much more complicated than that and would probably need to involve front-matter for each section to replace variables and stuff (e.g. in vinyl-fs, the examples use vfs.src/vfs.dest but those would need to become gulp.src/gulp.dest) in the gulp repo.

@phated
Copy link
Member Author

phated commented Jan 29, 2018

hey everyone, we're still looking for help improving the docs for 4.0 - would love any sort of help!

@selrond
Copy link

selrond commented Mar 21, 2018

@phated I could probably help with something - what could it be?

@icarter09
Copy link

@phated are you still needing help with improving the v4.0 docs?

@phated
Copy link
Member Author

phated commented Oct 25, 2018

I'm going to close this since we have the Getting Started and API docs done. We already have another issue (#2164) opened for Recipes and I'll be creating a couple other issues for other pieces that still need to be worked on.

@phated phated closed this as completed Oct 25, 2018
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

10 participants