[Docs] Documentation and versioning

[ldesplat]

Documentation on the react website seems to be from the master version? It is very confusing when developing from the stable version where you expect some things to work but they don't. (renderSeparator for me last week).

There should be some way to browse "older" documentation and most likely it should default to the stable version and not rc.

Food for thought 👍

[umhan35]

This is great but I think Facebook lacks resources on this project somehow.

[brentvatne]

The docs serve the OSS community and should be driven by us as well.

If you would like to browse the older documentation you can actually just run the server locally very easily - clone the repo and check out the version you are interested in, then cd into the website directory and run node server/server.js - this will start up a docs webserver locally and you can now browse it.

But you're right that it should default to stable and not rc. We discussed this a bit in #1022, @arthuralee perhaps you and @ldesplat can collaborate on coming up with a solution for this?

[jtremback]

How about we have the main site pull docs from the version of RN that is on NPM? This would seem to be the correct version in any case.

@umhan35 I'm guessing that FB's apps are running master, so it makes no sense for them to work on this, which only benefits people who are not using master.

[ide]

The main site should match npm, and ideally there would be docs for RC (both to document RC and to act as a staging release in case there's a problem with the docs site) and master. I'm not so familiar with Jekyll and GH pages... is it easy to "reparent" a site so that it could live under https://facebook.github.io/react-native/rc/ or https://facebook.github.io/react-native/master, and customize the CSS a bit to add a banner at the top with the version info?

[jaredly]

react-native gh-pages doesn't use jekyll -- there's custom script that downloads the html from the localhost docs server :) it wouldn't be too hard to hack it https://github.com/facebook/react-native/blob/master/website/server/generate.js

[arthuralee]

I agree that the docs on the site should reflect whats on npm. We do, however, lose the ability to make quick bugfixes to the documentation, as discussed in #1022. I still think a version picker would be very useful in the long term. However, for now, we could just have links to stable, RC, and maybe master.

Yes, the site is generated as @jaredly mentioned, and Travis runs the script (see https://github.com/facebook/react-native/blob/master/.travis.yml#L39-L49). Right now, publish.sh seems to clear out the site and regenerate it. As a starting point we could checkout the latest stable and RC and generate those into subfolders.

[brentvatne]

@arthuralee 👍 to the version picker, between stable and RC is an excellent starting point

[ide]

If the new doc generator were to use the git tags (latest stable, latest rc, master) we'd still be able to quickly update the docs in an emergency by overwriting those tags (yay force push) to point to a new commit.

[brentvatne]

Hi there! This issue is being closed because it has been inactive for a while.

But don't worry, it will live on with ProductPains! Check out it's new home: https://productpains.com/post/react-native/docs-documentation-and-versioning