search

reduxjs / redux

A JS library for predictable global state management
https://redux.js.org
MIT License
60.91k stars 15.27k forks source link

Investigate alternative docs publishing solutions #3161

Closed markerikson closed 5 years ago

markerikson commented 6 years ago

I'm still not terribly happy with Gitbook as the solution for publishing our docs.

The good news is that the hosted version of Gitbook at least auto-publishes whenever we push to master, which is a vast improvement over the old docs publishing command we used to have to run manually.

However, there are several problems that still bother me:

I would like someone to investigate switching our docs to be built with some other static site generation solution, such as Docusaurus, Gatsby, or React-Static. I have no particular preference myself, although it would be nice on general principle if the solution was something React-based or similar.

The one thing that the hosted version of Gitbook seems to give us that's neat is the "did this help?" rating at the bottom of each page, but to be honest I don't think we've ever made any actual use of that information.

The content itself is also hosted/published on Gitbook's infrastructure, but there's obviously plenty of other options out there (Netlify being the biggest one, and I think that's the main React docs at https://github.com/reactjs/reactjs.org use - someone confirm?).

Our content is all Markdown already, so I would think it wouldn't be too hard to set up some alternative static site generator tool and start using the docs as the source.

Also, it would be beneficial if there was a good way to publish versioned docs, since we would likely want to use the same solution for React-Redux as well. In fact, perhaps React-Redux would make a better test case, since we don't even have its docs as a published site yet.

One other thought: when we do revamp the main Redux docs content, I would want to start moving around a bunch of our pages - recategorizing existing pages, as well as merging/changing others. It would be really beneficial if there's a good redirect solution as part of this. For example, if "Immutable Update Patterns" got moved from /structuring-reducers/immutableupdatepatterns to, say, /reducers/immutable-update-patterns, then I'd want to have a redirect in place so that external links don't break.

Thoughts? Volunteers?

sveinpg commented 6 years ago

@markerikson Docusaurus seems nice. I can try it out this weekend.

Would love to contribute

markerikson commented 6 years ago

Sure. @sw-yx has also offered to look into Docusaurus as well.

Per my comment above, perhaps it would be simpler to start with the React-Redux docs so we can get a feel for how this would work before trying to tackle the main Redux docs.

sveinpg commented 6 years ago

@markerikson Sure. Is there an issue for this?

markerikson commented 6 years ago

Don't have a separate issue set up for the React-Redux repo atm. Lemme clone this over there so we can track it separately.

markerikson commented 6 years ago

Done: https://github.com/reduxjs/react-redux/issues/1031

alexkrolick commented 6 years ago

The content itself is also hosted/published on Gitbook's infrastructure, but there's obviously plenty of other options out there (Netlify being the biggest one, and I think that's the main React docs at https://github.com/reactjs/reactjs.org use - someone confirm?).

yes

markerikson commented 6 years ago

So let's see. For point of reference, Babel's docs site appears to be built with Docusaurus ( https://github.com/babel/website ), and ReactJS.org is built with Gatsby ( https://github.com/reactjs/reactjs.org )

markerikson commented 6 years ago

Per comments in https://github.com/reduxjs/react-redux/issues/1031 , I've set up a temp page at https://react-redux-docs.netlify.com , and just created another project at https://redux-docs.netlify.com .

We can figure out details of how to work with them as we go.

timdorr commented 6 years ago

I'm a fan of what's going on with Gatsby. I'd be interested in that.

The biggest advantage of Gitbook is the rather plain way of describing your docs structure via a Summary.md file. Can we emulate that somehow? It makes it really easy to read the raw markdown on either GitHub or directly on your computer locally.

markerikson commented 6 years ago

Looking at the generated Docusaurus structure in https://github.com/reduxjs/react-redux/pull/1032 , it looks like it relies on a a combination of some ID added to the front matter of each Markdown file, and a JSON config file with an array of IDs in categories.

I suppose we could do something fancy with parsing a Markdown list and generating the sidebars.json based on that, but I doubt it's worth the extra step.

I have to say that Docusaurus's feature list looks excellent (particularly the versioning and localization aspects), and Babel's docs site looks pretty good as a result.

Also, per my questions about redirects, Netlify supports them via a _redirects file added to the root of the published site (see Babel's _redirects file as an example).

alexkrolick commented 6 years ago

There's a lot of custom code to put the React site together with Gatsby; if you can do it with Docusaurus that seems like it would be a lot easier to set up and maintain.

markerikson commented 6 years ago

I know you've spent a bunch of time working on the React docs lately. Got any summary on what kinds of custom features they have set up?

I don't think we need anything too fancy. Versioning and localization look like a couple of the trickiest bits we would want.

Looking at the list of existing Docusaurus-based sites linked from its home page, I can see a form of the "Bootstrap effect" showing up in that most of them are just recolors of the default theme. But, I'm okay with that for now - function over form :)

Note that all this commentary doesn't mean that I'm saying we're definitely choosing Docusaurus - it's just that the first person to pop in with a PR for React-Redux did so for Docusaurus, the list of features it offers seems pretty good, and it seems to fit the criteria I listed above.

Again, part of the point of this is that I don't have time to experiment with this different tools myself. I have a decent idea what I want the final workflow and functionality to be like, so I'm mostly caring about the result. If someone who's got Gatsby experience wants to throw together a PR for React-Redux so that we can compare, go for it!

markerikson commented 6 years ago

I've just merged #3165 , which contains the major work to set up a Docusaurus build for our docs. They're currently visible at https://redux-docs.netlify.com/ .

Our next step is to figure out what is missing, broken, or otherwise lacking in parity compared to the current docs. From there, we can also start figuring out any actual improvements we want to make.

Purely off the top of my head, a couple items from each category:

alexkrolick commented 6 years ago

That site looks nice!

Got any summary on what kinds of custom features they have set up?

Pretty much everything is "custom" in that in Gatsby you start with a boilerplate at most. There's no real "Gatsby but for docs only" that you upgrade in a framework-like way. You have more control but more responsibility as well.

Aside from the layout there are some custom plugins here: https://github.com/reactjs/reactjs.org/tree/master/plugins

Brian (and many other helpful people) have contributed a fair amount upstream for some of the markdown plugins to add line highlighting and things like that: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-embed-snippet

yangshun commented 6 years ago

@markerikson Which of the points you mentioned are of higher priority? I could look into implementing some of them for Docusaurus.

The codesandbox embeds support sound interesting and useful. @sveinpg mentioned them to me before too.

markerikson commented 6 years ago

@yangshun : getting the URLs to match exactly would be highest priority. There's thousands of external links pointing to the existing docs page, and the simplest thing here is to make sure our new site matches the old structure exactly when it goes live. I want to shuffle things around later, but we need to get everything matched up as-is first.

The FAQ "short anchor links" were originally implemented by adding a <a name="some-short-readable-name"> tag right before a ## Some Much Longer Question Title? line. It worked, mostly - the <a> tag got included in the output HTML, and the hand-written TOCs at the top of each FAQ page explicitly linked to those readable names.

I doubt there's a good automatic way to generate those, and there probably isn't a good way to make the auto-generated right side TOC refer to those anchors if we put them in by hand. But, I'm certainly up for any ideas.

(Also, apparently the <a name=""> attribute isn't really a thing anymore?)

markerikson commented 5 years ago

Took a look at this again today. Status:

One blocker I found: it seems that Docusaurus isn't properly parsing Markdown links between pages, like [link text here](./SomeFile.md), so all our inter-page links are broken on this branch. (As an example, see the "Store" API page and try clicking on "state tree", or the "Reducers" page and click on the "actions" link.)

I filed https://github.com/facebook/Docusaurus/issues/1137 , and @endiliey is looking at it since I was able to provide a repro.

Also, it looks like page URLs are based on the id values in the front matter, so if we want to have Docusaurus generating URLs that are identical to what we have now, we'd need to modify the IDs appropriately.

I'd like to continue focusing attention on this and push it forward in the near future.

markerikson commented 5 years ago

Spent all of today working on this, and got some assistance from @endiliey and @ghardin137 .

PRs:

Current status:

I think we're actually getting pretty close here. Things I know that still need to be done:

sveinpg commented 5 years ago

Great work @markerikson

You, or Tim, should enable the search since you are the maintainer(s) of the project.

I created a PR that fixes the hidden title on mobile (https://github.com/reduxjs/redux/pull/3274)

Let me know if there is anything else you need help with.

markerikson commented 5 years ago

Getting real close!

@sveinpg set up a 404 page ( #3276 ), and I added redirects from the old docs URLs (#3277 ) and fiddled with landing page formatting on mobile ( #3278 ).

@endiliey pointed me at Algolia's "DocSearch" program, which was already set up for React-Redux, so I requested search API keys for Redux and Redux-Starter-Kit. I want to have search enabled before we flip the DNS switch.

On that note, DNS will be a 2-part process: I'll need to file a PR against the js.org repo, and once that's ready, I need to update the Netlify site config. Not quite sure on the timing specifics there.

Other than that, I think the site is probably about ready to go. Might still be a few rough edges somewhere, but should be sufficient to make it live once search is ready.

edit

Almost forgot, someone was volunteering to do some a11y / style tweaks. Don't have to wait for those to go live, but those will hopefully come in soon.

markerikson commented 5 years ago

I got a response from an Algolia rep this morning. Looks like they need the new site to be live at its final address before they can set up the docs search stuff on their end. So, we'll have to make the DNS switch first and have the new site be live but without search for a bit.

I think the last tweak I want to make tonight is to have each of the three docs sites cross-link each other on the front page, below the sales pitch section. I'll try to figure out some good formatting for that.

markerikson commented 5 years ago

Tonight's tweaks:

At this point, I'm just waiting for the js.org folks to give me a thumbs-up and say that the DNS switch is ready to go.

markerikson commented 5 years ago

AAAND we are LIVE at https://redux.js.org !!!

Thank you SO much to everyone who's contributed to this!

I'll take care of merging the docs-rebuild branch back into master and fiddling with the build config stuff in the next day or so.

With that, we can now turn our attention to seriously planning a rewrite of the content. Please see #2590 for existing discussion on that topic.

I've got a survey asking for feedback at https://docs.google.com/forms/d/e/1FAIpQLSfzIkY3fXZ8PrQKScYMK0YoEgALfAK2qQ0mOj1_ibKv2qDTuQ/viewform . I'll post the results in that thread at some point.

markerikson commented 5 years ago

Just merged the docs-rebuild branch into master.