fix #152 improve documentation #222

vinnymac · 2017-06-28T14:28:45Z

The goal here is to improve documentation. Both the documentation and the user experience around that documentation require changes.

Use gitbook to keep documentation style consistent across redux projects (redux and redux-saga)
Add TOCs
Make the docs less long and unruly
Close Readme createActions example incorrect #172 documentation issue
Close Missing handleAction example with a reducer function in README #204 documentation issue
Add a Beginner Tutorial with Demo and Installation instructions
Use js.org so that people can access the docs via redux-actions.js.org

New Documentation Demo

Auto commit by GitBook Editor

yangmillstheory · 2017-06-28T20:01:13Z

Are those checkboxes still outstanding? Let me know when I should start review (might be not be until this weekend on my end).

yangmillstheory · 2017-06-28T20:01:46Z

Also is there a URL where I can see the docs site?

Auto commit by GitBook Editor

vinnymac · 2017-06-28T21:19:17Z

@yangmillstheory yea this is just a starting point for the PR. Nowhere near finished. Here is where you can find the new docs site. Once I am close to finished I guess we will have to discuss getting redux-actions.js.org setup.

Auto commit by GitBook Editor

vinnymac · 2017-07-03T00:15:37Z

@yangmillstheory https://redux-actions.js.org/

I think the DNS still needs to be configured though.

yangmillstheory · 2017-07-03T00:42:50Z

What do you mean that the DNS still needs to be configured? js-org/js.org#1333 looks like it created the CNAME to your gitbook URL.

Later we can self-host the site using GitHub Pages (I emailed @acdlite and CC'ed you). For now, thanks for hosting.

I can take another look tonight; is there anything else you would like to include?

vinnymac · 2017-07-03T01:15:03Z

Gitbook was giving me an error when I configured it. But maybe you are right. In my experience you usually have to wait a little while for the records to update, so I figure that is why gitbook is upset.

Doing one last look over can't hurt. Thanks for all the help by the way. It has been greatly appreciated.

yangmillstheory · 2017-07-03T02:49:41Z

No problem; this is a huge win for the project, thanks for taking the initiative.

yangmillstheory · 2017-07-03T02:50:22Z

Does the Edit functionality work now?

yangmillstheory · 2017-07-03T02:51:22Z

build/gitbook.css

@@ -0,0 +1,3 @@
+.token.operator {
+  background: none;
+}


~~Should this folder be checked in?~~ Actually this directory is checked in. But why is this file here - locally this directory contains just a couple of files for me:

preset-es2015.js

use-lodash-es.js

yangmillstheory · 2017-07-03T02:55:22Z

package.json

+    "docs:prepare": "gitbook install",
+    "docs:build": "npm run docs:prepare && gitbook build -g acdlite/redux-actions",
+    "docs:watch": "npm run docs:prepare && gitbook serve",
+    "docs:publish": "npm run docs:clean && npm run docs:build && cp CNAME _book && cd _book && git init && git commit --allow-empty -m 'update book' && git checkout -b gh-pages && touch .nojekyll && git add . && git commit -am 'update book' && git push git@github.com:acdlite/redux-actions gh-pages --force"


Does this need to be run separately from npm publish? Can we use the postpublish hook to run this?

Well I guess technically just because you are releasing a new version of the library on npm doesn't necessarily mean you are releasing new documentation. If you want it to be part of that process though I don't see why it couldn't be added to postpublish. I added that more for convenience in case you wanted it on gh-pages like we planned.

OK it's up to you, we can leave it out for now. By the way, how will this work if I want to publish new documentation, since it's hosted in your gitbook URL? Do we need to grant access to developers of this repo until @acdlite sets up pushing to GitHub pages (I don't have access to the repository settings)?

I have given both you and @acdlite full administrative privileges over the gitbook. We will likely want to get it done the other way asap so others can be able to contribute without requiring access.

I agree; it's up to him to respond to the email at this point.

yangmillstheory · 2017-07-03T03:05:02Z

@vinnymac just a couple of questions:

vinnymac · 2017-07-03T03:51:47Z

The Edit functionality is pointing to master right now, so that won't work unless we merged it to master. I could have it point to my fork, but I don't think that is what we want. So we either merge it to master or we merge it to a separate branch and link to that one.

yangmillstheory · 2017-07-03T05:26:50Z

OK, will merge by midnight.

On Sun, Jul 2, 2017 at 8:51 PM Vincent Taverna ***@***.***> wrote: The Edit functionality is pointing to master right now, so that won't work unless we merged it to master. I could have it point to my fork, but I don't think that is what we want. So we either merge it to master or we merge it to a separate branch and link to that one. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#222 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACmkd39wil6S6NUrlwoucuzVUG7JyKIUks5sKGVUgaJpZM4OIC86> .

-- Victor Alvarez

yangmillstheory · 2017-07-03T05:58:57Z

Hm, some of the links are broken - try clicking around on the documentation site from the home page.

yangmillstheory · 2017-07-03T06:08:41Z

@vinnymac I just pushed the fixes to master; how can I push the changes to your gitbook?

vinnymac · 2017-07-03T10:57:20Z

@yangmillstheory somehow the links were pointing to /api instead of /docs/api. Not sure what happened exactly, but I ended up updating vinnymac/redux-actions/tree/master to the latest and pointing gitbook at that branch and it seems to have fixed the issue for me.

I could always transfer ownership of the entire gitbook to you. But I can't seem to find a way to switch from one repository to another because I don't see acdlite/redux-actions in the list on the settings page. If you navigate here can you try to link it to this repository instead of mine? May be a permissions thing.

EDIT
Oh weird, so I guess I didn't fix it. If you go directly to the documentation site the links work fine. But for some reason if you use the links in the main README.md on the bottom it throws the whole thing off. Maybe we should try updating those links to be absolute paths.

EDIT 2
Yea if you look at how redux-saga does it, they point directly to the html file on the docs site, and not the relative markdown. I'll make a new PR to fix it.

yangmillstheory · 2017-07-03T15:55:04Z

Thanks. I can't connect your GitBook to this repo (don't have access to the settings page, and the integration is configured there).

I guess we'll just have to wait for a response from @acdlite. It's the holiday after all though. So it looks like the current fix is to fix it your repo, and merge the changes back here (won't do anything but keep things in sync).

yangmillstheory · 2017-07-08T05:07:50Z

@vinnymac for now, is there a place others can submit documentation PRs to to update the redux-actions.js.org?

timche · 2017-07-08T08:06:38Z

@yangmillstheory try to contact him on Twitter. I assume he has muted this repo.

vinnymac · 2017-07-08T14:34:33Z

@yangmillstheory if you make a PR to the master branch of vinnymac/redux-actions it will automatically update the docs once merged. Until acdlite responds I guess that is just how it will have to be done.

yangmillstheory · 2017-07-08T16:42:36Z

Will do tim, I actually emailed him at the address on his profile.

vinnymac added 4 commits June 28, 2017 10:04

add npm scripts for docs

785cc94

add cname for js.org

2869aa1

add docs folder with some tocs

7e9a9cd

add gitbook cli as dev dependency

4ea504f

vinnymac changed the title ~~Docs Site~~ fix #152 improve documentation Jun 28, 2017

vinnymac added 13 commits June 28, 2017 10:41

ignore _book docs dir

28db569

ignore list for gitbook

4358370

npmignore for gitbook files

2eefbae

add summary

7965e45

add config for gitbook

ab22912

ignore more gitbook files

a10471f

add styling tweak to gitbook

084790a

add external resources md

94bbf34

Updates docs/api/README.md

4b2d0bd

Auto commit by GitBook Editor

Updates docs/api/README.md

605f6e5

Auto commit by GitBook Editor

Updates docs/api/README.md

62fa586

Auto commit by GitBook Editor

Updates docs/api/README.md

f105653

Auto commit by GitBook Editor

Updates docs/api/README.md

cfb8720

Auto commit by GitBook Editor

yangmillstheory self-requested a review June 28, 2017 20:00

vinnymac added 2 commits June 28, 2017 20:36

Updates SUMMARY.md

182ea1a

Auto commit by GitBook Editor

Merge branch docs into docs

e95a653

vinnymac added 6 commits June 29, 2017 14:27

Updates docs/README.md

d4cb330

Auto commit by GitBook Editor

Merge d4cb330 into docs

e098244

Updates docs/introduction/BeginnerTutorial.md

2491d7d

Auto commit by GitBook Editor

Updates README.md

c8ac56d

Auto commit by GitBook Editor

Updates docs/introduction/12-motivation.md

7e4a3ea

Auto commit by GitBook Editor

Updates docs/introduction/README.md

04c0cea

Auto commit by GitBook Editor

change method page headers

610dc17

vinnymac and others added 3 commits July 2, 2017 20:21

Merge branch 'master' into docs

b1bc4f0

restore changes to createAction docs

6251467

restore changes to handleActions docs

1148ceb

use github handles

6d12354

yangmillstheory reviewed Jul 3, 2017

View reviewed changes

yangmillstheory added 2 commits July 2, 2017 20:00

use markdown links

2d4a57b

link to canonical host

c42a5c5

vinnymac added 2 commits July 2, 2017 23:34

remove unnecessary css file

f3bfe59

remove default theme config

ad85743

yangmillstheory merged commit a99796b into redux-utilities:master Jul 3, 2017

vinnymac deleted the docs branch July 3, 2017 18:05

mslipper mentioned this pull request Dec 20, 2017

Add handleAction example with a reducer function to README #205

Closed

timche mentioned this pull request Apr 24, 2018

redux-actions.js.org js-org/js.org#1934

Merged

fix #152 improve documentation #222

fix #152 improve documentation #222

Uh oh!

Conversation

vinnymac commented Jun 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yangmillstheory commented Jun 28, 2017

Uh oh!

yangmillstheory commented Jun 28, 2017

Uh oh!

vinnymac commented Jun 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vinnymac commented Jul 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yangmillstheory commented Jul 3, 2017

Uh oh!

vinnymac commented Jul 3, 2017

Uh oh!

yangmillstheory commented Jul 3, 2017

Uh oh!

yangmillstheory commented Jul 3, 2017

Uh oh!

yangmillstheory Jul 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yangmillstheory Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

vinnymac Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

yangmillstheory Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

vinnymac Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

yangmillstheory Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

yangmillstheory commented Jul 3, 2017

Uh oh!

vinnymac commented Jul 3, 2017

Uh oh!

yangmillstheory commented Jul 3, 2017 via email

Uh oh!

yangmillstheory commented Jul 3, 2017

Uh oh!

yangmillstheory commented Jul 3, 2017

Uh oh!

vinnymac commented Jul 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yangmillstheory commented Jul 3, 2017

Uh oh!

yangmillstheory commented Jul 8, 2017

Uh oh!

timche commented Jul 8, 2017

Uh oh!

vinnymac commented Jul 8, 2017

Uh oh!

yangmillstheory commented Jul 8, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vinnymac commented Jun 28, 2017 •

edited

Loading

vinnymac commented Jun 28, 2017 •

edited

Loading

vinnymac commented Jul 3, 2017 •

edited

Loading

yangmillstheory Jul 3, 2017 •

edited

Loading

vinnymac commented Jul 3, 2017 •

edited

Loading