Adds a new docs website, built with Gatsby JS, to replace the old Jekyll site. Source code for the new site lives in /www (although markdown and YML data still comes from the legacy /docs folder).
Changes to either markdown or website source code can be previewed on Netlify. The react-js bot should automatically add comments to each PR with preview links. (This preview is generated by running the newly-added yarn build:docs command in the root package.json.)
The majority of the changes in this PR are contained within the new /www directory. However some minor modifications have been made to existing content in the /docs directory:
* Modified frontmatter author block to always be an array
* Small markdown formatting tweaks
* Add 'Test Utils' docs back to main navigation
**why make this change?:**
We accidentally removed this - still supporting the use of Test Utilities, so we should have them in the docs.
**test plan:**
Manually tested the website - will insert a screenshot.
**issue:**
https://github.com/facebook/react/issues/9651
* Move test-utils docs to reference section
**what is the change?:**
Moved from 'advanced guides' to 'reference'
**why make this change?:**
It makes more sense as a reference
**test plan:**
Visual inspection (flarnie may add a screenshot)
**issue:**
* Add back the shallow renderer docs and remove outdated docs
**what is the change?:**
- Remove outdated 'shallow renderer' docs on 'test utils' page, and point to the updated 'shallow renderer' docs.
- Re-add a link to the updated 'shallow renderer' docs on the main navigation.
**why make this change?:**
This was already approved in https://github.com/facebook/react/pull/9331 which was then cherry-picked to https://github.com/facebook/react/pull/9359/commits and landed on master.
I'm not sure why some of these changes didn't persist. For now just adding back the changes we need.
**test plan:**
Manually inspected website - will insert screenshots.
**issue:**
* Further improvements to 'shallow rendering' and 'test utils' docs
Thanks @gaearon for the improvements!
**what is the change?:**
- Remove <hr/> from end of 'shallow rendering' docs
- 'documents' -> 'documentation'
- Move 'shallow rendering' redirection section to top of 'test utils' docs
- Add intro sentence about testing to 'shallow rendering' docs
**why make this change?:**
Documentation helps people learn.
**test plan:**
Visual inspection
* `react-addons-test-utils` -> `react-dom/test-utils`
Updating all references and docs on the `React.addons.TestUtils` and the
shallow renderer to refer to the correct targets.
Instead of:
```
const React = require('react');
// ...
React.addons.Testutils
// or
const ReactTestUtils = require('react-addons-test-utils');
```
we now show:
```
const ReactTestUtils = require('react-dom/test-utils');
```
And for shallow renderer, instead of:
```
const shallowRenderer = TestUtils.createRenderer();
```
we now show:
```
const shallowRenderer = require('react-test-renderer/shallow');
```
* Update the 'prev' and 'next' attributes of 'add-ons' docs
These flags are used to set arrow links to easily navigate through the
documents. They were wrong or missing in some of the 'add-ons' pages and
this bothered me when manually testing the updates from the previous
commit.
* Update syntax for instantiating shallow renderer
Missed this when updating the docs for the changes to shallow-renderer
in React 15.5.
* Fix pointers in addons docs
Thanks @bvaughn for catching this
* Make example of shallow renderer more consistent
We should show using the same variable names between code samples.
* Make names in example even more consistent
We should use the same variable name for the same thing across examples.
`renderer` -> `shallowRenderer`.
* Update docs to deprecate React<CSS>TransitionGroup
- removes link to the docs about `ReactCSSTransitionGroup` and
`ReactTransitionGroup` from the main navigation
- updates 'prev' and 'next' pointers to skip this page
- adds deprecation warning to the top of the page
- remove references to these modules from the packages README
- updates 'add-ons' main page to list this as a deprecated add-on
* Update `React.createClass` to `createReactClass` in the docs
The `React.createClass` method is being deprecated in favor of
`createReactClass`.
* Remove 'React.createClass' from top level API docs
It no longer makes sense to have a section for the 'createClass' method
in this page, since it won't be available as a top level method on
'React'.
I initially was going to pull the section about 'createClass' into a
separate page to add under 'addons' but it was short and duplicative of
the 'react-without-es6' docs. So I just linked to those.
* Remove *most* `React.PropTypes` from the docs
I am doing the docs for `context` in a separate commit because that case
was a bit less clear-cut.
We will no longer support `React.PropTypes` as a built-in feature of
React, and instead should direct folks to use the `PropTypes` project
that stands alone.
Rather than retaining the `React.PropTypes` examples and just revamping
them to show the use of the stand-alone `PropTypes` library with React,
it makes more sense to direct people to that project and reduce the
perceived API area and complexity of React core. The proper place to
document `PropTypes` is in the README or docs of that project, not in
React docs.
* Update `context` docs to not use `React.PropTypes`
We use `React.PropTypes` to define the `contextType` for the `context`
feature of React. It's unclear how this will work once `React.PropTypes`
is replaced by the external `PropTypes` library. Some options;
a) Deprecate `context`, either in v16 or shortly after. Seems reasonable
based on the intense warnings against using context that we have in the
docs -
https://facebook.github.io/react/docs/context.html#why-not-to-use-context
**Except** that probably some widely used libraries depend on it, like
`React-Router`.
b) Expect users will use external `PropTypes` library when defining
`contextTypes` and just don't do our `checkReactTypeSpec` against them
any more in v16.
c) Stop masking context and pass the whole context
unmasked everywhere. Worst option, do not recommend.
I went with `b` and assume that, for now, we will get users to use the
external `PropTypes` when defining context. I will update this PR if we
want a different approach.
* Remove 'addons' items from left nav, and deprecate 'addons' doc page
The plan:
[X] Remove links to 'addons' items from main navigation
[X] Add deprecation notices where appropriate, and update syntax to show
using the separate modules.
[ ] Update other references to 'React.addons' in docs. Coming in next
commit.
--- blocked but coming in future PRs
[ ] Link to a blog post describing the new locations of add-ons in the
deprecation notice on the '/docs/addons.html' page. Blocked until we
actually publish that blog post.
[ ] Move the docs for each add-on to the actual github repo where it now
lives.
[ ] Redirect the old add-ons doc permalinks to the docs in the separate
github repos for those modules.
[ ] Remove the old add-ons doc markdown files from React core docs.
* Remove references to `React.addons` from docs
Just misc. places where we referenced the 'addons' feature. All gone!
Ricky
Michał Gołębiowski-Owczarek
Nat Alison
Brian Vaughn
Dan Abramov
Flarnie Marchan