Flarnie MarchanandDan Abramov
d5c3afda2f
* 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
(cherry picked from commit 114b9c5500)
React Documentation & Website
We use Jekyll to build the site using (mostly) Markdown, and we host it by pushing HTML to GitHub Pages.
Installation
If you are working on the site, you will want to install and run a local copy of it.
Dependencies
In order to use Jekyll, you will need to have Ruby installed.
Mac OS X comes pre-installed with Ruby, but you may need to update RubyGems (via gem update --system).
Otherwise, RVM and rbenv are popular ways to install Ruby.
Once you have RubyGems and installed Bundler (via gem install bundler), use it to install the dependencies:
$ cd react/docs
$ bundle install # Might need sudo.
$ npm install
Instructions
The site requires React, so first make sure you've built the project (via grunt).
Use Jekyll to serve the website locally (by default, at http://localhost:4000):
$ cd react/docs
$ bundle exec rake
$ bundle exec jekyll serve -w
$ open http://localhost:4000/react/index.html
We use SASS (with Bourbon) for our CSS, and we use JSX to transform some of our JS. If you only want to modify the HTML or Markdown, you do not have to do anything because we package pre-compiled copies of the CSS and JS. If you want to modify the CSS or JS, use Rake to compile them:
$ cd react/docs
$ bundle exec rake watch # Automatically compiles as needed.
# bundle exec rake Manually compile CSS and JS.
# bundle exec rake js Manually compile JS, only.
Afterthoughts
Updating facebook.github.io/react
The easiest way to do this is to have a separate clone of this repository, checked out to the gh-pages branch. We have a build step that expects this to be in a directory named react-gh-pages at the same depth as react. Then it's just a matter of running grunt docs, which will compile the site and copy it out to this repository. From there, you can check it in.
Note: This should only be done for new releases. You should create a tag corresponding to the release tag in the main repository.
We also have a rake task that does the same thing (without creating commits). It expects the directory structure mentioned above.
$ bundle exec rake release
Removing the Jekyll / Ruby Dependency
In an ideal world, we would not be adding a Ruby dependency on part of our project. We would like to move towards a point where we are using React to render the website.