Cleanup troubleshooting and debugging docs.

Summary:
This is a followup to facebook#8010. Troubleshooting has been updated to list only those issues that may affect a user that is setting up their environment. Any issues related to day to day use have been moved or merged into a more relevant doc.
Closes facebook#8254

Reviewed By: caabernathy

Differential Revision: D3459018

Pulled By: JoelMarcey

fbshipit-source-id: dd76097af34bd33dda376fab39fb0f71061ef3e4

Author: hramos

docs/Debugging.md

@@ -7,48 +7,54 @@ permalink: docs/debugging.html
 next: testing
 ---
 
-## In-app Errors and Warnings
-
-Errors and warnings are displayed inside your app in development builds.
-
-### Errors
-
-In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use `console.error()` to manually trigger one.
-
-### Warnings
-
-Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them.
-
-As with a RedBox, you can use `console.warn()` to trigger a YellowBox.
-
-YellowBoxes can be disabled during development by using `console.disableYellowBox = true;`. Specific warnings can be ignored programmatically by setting an array of prefixes that should be ignored: `console.ignoredYellowBox = ['Warning: ...'];`
-
-> RedBoxes and YellowBoxes are automatically disabled in release (production) builds.
-
 ## Accessing the In-App Developer Menu
 
-You can access the developer menu by shaking your device. You can also use the `Command⌘ + D` keyboard shortcut when your app is running in the iPhone Simulator, or `Command⌘ + M` when running in an Android emulator.
+You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. You can also use the `Command⌘ + D` keyboard shortcut when your app is running in the iPhone Simulator, or `Command⌘ + M` when running in an Android emulator.
+
+![](img/DeveloperMenu.png)
 
 > The Developer Menu is disabled in release (production) builds.
 
 ## Reloading JavaScript
 
 Selecting `Reload` from the Developer Menu will reload the JavaScript that powers your application. You can also press `Command⌘ + R` in the iOS Simulator, or press `R` twice on Android emulators.
 
+> If you are using a Dvorak/Colemak layout, use the `Command⌘ + P` keyboard shortcut to reload the simulator.
+
 You will need to rebuild your app for changes to take effect in certain situations:
 
 * You have added new resources to your native app's bundle, such as an image in `Images.xcassets` on iOS or in `res/drawable` folder on Android.
 * You have modified native code (Objective-C/Swift on iOS or Java/C++ on Android).
 
+> If the `Command⌘ + R` keyboard shortcut does not seem to reload the iOS Simulator, go to the Hardware menu, select Keyboard, and make sure that "Connect Hardware Keyboard" is checked.
+
 ### Automatic reloading
 
 You may enable Live Reload to automatically trigger a reload whenever your JavaScript code changes.
 
 Live Reload is available on iOS via the Developer Menu. On Android, select "Dev Settings" from the Developer Menu and enable "Auto reload on JS change".
 
+## In-app Errors and Warnings
+
+Errors and warnings are displayed inside your app in development builds.
+
+### Errors
+
+In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use `console.error()` to manually trigger one.
+
+### Warnings
+
+Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them.
+
+As with a RedBox, you can use `console.warn()` to trigger a YellowBox.
+
+YellowBoxes can be disabled during development by using `console.disableYellowBox = true;`. Specific warnings can be ignored programmatically by setting an array of prefixes that should be ignored: `console.ignoredYellowBox = ['Warning: ...'];`
+
+> RedBoxes and YellowBoxes are automatically disabled in release (production) builds.
+
 ## Accessing logs
 
-To view detailed logs on iOS, open your app in Xcode, then Build and Run your app on a device or the iPhone Simulator. The console should appear automatically after the app launches.
+To view detailed logs on iOS, open your app in Xcode, then Build and Run your app on a device or the iPhone Simulator. The console should appear automatically after the app launches. If your app is failing to build, check the Issues Navigator in Xcode.
 
 Run `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal to display the logs for an Android app running on a device or an emulator.
 
@@ -68,6 +74,8 @@ On Android 5.0+ devices connected via USB, you can use the [`adb` command line t
 
 Alternatively, select `Dev Settings` from the Developer Menu, then update the `Debug server host for device` setting to match the IP address of your computer.
 
+> If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.
+
 ### Debugging using a custom JavaScript debugger
 
 To use a custom JavaScript debugger in place of Chrome Developer Tools, set the `REACT_DEBUGGER` environment variable to a command that will start your custom debugger. You can then select `Debug JS Remotely` from the Developer Menu to start debugging.

docs/QuickStart-GettingStarted.md

@@ -282,6 +282,8 @@ Congratulations! You've successfully run and modified your first React Native ap
 
 ## Common Followups
 
+- Learn how to access the Developer Menu, reload your JavaScript, access logs, and more in the [Debugging guide](docs/debugging.html#content).
+
 <block class="mac ios" />
 
 - If you want to run on a physical device, see the [Running on iOS Device page](docs/running-on-device-ios.html#content).
@@ -292,15 +294,17 @@ Congratulations! You've successfully run and modified your first React Native ap
 
 <block class="mac ios android" />
 
-- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) and [Debugging](docs/debugging.html#content) pages.
+- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) page.
 
 <block class="windows linux android" />
 
 ## Common Followups
 
+- Learn how to access the Developer Menu, reload your JavaScript, access logs, and more in the [Debugging guide](docs/debugging.html#content).
+
 - If you want to run on a physical device, see the [Running on Android Device page](docs/running-on-device-android.html#content).
 
-- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) and [Debugging](docs/debugging.html#content) pages.
+- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) page.
 
 <script>
 // Convert <div>...<span><block /></span>...</div>

docs/RunningOnDeviceIOS.md

@@ -11,7 +11,7 @@ Note that running on device requires [Apple Developer account](https://developer
 
 ## Accessing development server from device
 
-You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.
+You can iterate quickly on device using development server. Ensure that you are on the same WiFi network as your computer.
 
 1. Open `AwesomeApp/ios/AwesomeApp/AppDelegate.m`
 2. Change the IP in the URL from `localhost` to your laptop's IP. On Mac, you can find the IP address in System Preferences / Network.

docs/Troubleshooting.md

@@ -6,69 +6,51 @@ category: Quick Start
 permalink: docs/troubleshooting.html
 ---
 
-## Cmd-R does not reload the simulator
-Enable iOS simulator's "Connect hardware keyboard" from menu Hardware > Keyboard menu.
+These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try [searching for the issue in GitHub](https://github.com/facebook/react-native/issues/).
 
-![Keyboard Menu](https://cloud.githubusercontent.com/assets/1388454/6863127/03837824-d409-11e4-9251-e05bd31d978f.png)
+### Port already in use
 
+The React Native packager runs on port 8081. If another process is already using that port (such as McAfee Antivirus on Windows), you can either terminate that process, or change the port that the packager uses.
 
-If you are using a non-QWERTY/AZERTY keyboard layout you can use the `Hardware > Shake Gesture` to bring up the dev menu and click "Refresh". Alternatively, you can hit `Cmd-P` on Dvorak/Colemak layouts to reload the simulator.
+#### Terminating a process on port 8081
 
-You can use Cmd+M on Android to bring up the dev menu.
+Run the following command on a Mac to find the id for the process that is listening on port 8081:
 
-## Port already in use red-screen
-![red-screen](https://cloud.githubusercontent.com/assets/602176/6857442/63fd4f0a-d3cc-11e4-871f-875b0c784611.png)
-
-
-Something is probably already running on port 8081. You can either kill it or try to change which port the packager is listening to.
-
-##### Kill process on port 8081
 `$ sudo lsof -n -i4TCP:8081 | grep LISTEN`
 
-then
+Then run the following to terminate the process:
 
-`$ kill -9 <cma process id>`
+`$ kill -9 <PID>`
 
+#### Using a port other than 8081
 
-##### Change the port in Xcode
-Edit `AppDelegate.m` to use a different port.
-```
-  // OPTION 1
-  // Load from development server. Start the server from the repository root:
-  //
-  // $ npm start
-  //
-  // To run on device, change `localhost` to the IP address of your computer, and make sure your computer and
-  // iOS device are on the same Wi-Fi network.
-  jsCodeLocation = [NSURL URLWithString:@"http://localhost:9381/index.ios.bundle"];
-  ```
+You can configure the packager to use a port other than 8081 by using the `port` parameter:
 
+`$ react-native start --port=8088`
 
-## Watchman took too long to load
-Permission settings prevent Watchman from loading. A recent update solves this, get a HEAD install of Watchman if you are experiencing this error.
+You will also need to update your applications to load the JavaScript bundle from the new port.
+
+To change the port used by an iOS application, edit the `AppDelegate.m` file in the `ios` folder. Scroll down to the line where the bundle location is defined, and replace 8081 with the new port.
 
 ```
-brew uninstall watchman
-brew install --HEAD watchman
+jsCodeLocation = [NSURL URLWithString:@"http://localhost:8088/index.ios.bundle"];
 ```
 
-## NPM locking error
+### NPM locking error
+
+If you encounter an error such as "npm WARN locking Error: EACCES" while using the React Native CLI, try running the following:
 
-If in the `react-native init <project>` phase you saw npm fail with "npm WARN locking Error: EACCES" then try the following:
 ```
 sudo chown -R $USER ~/.npm
 sudo chown -R $USER /usr/local/lib/node_modules
 ```
 
-## Debugging in Chrome hangs and/or does not work well
-It is possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. If you are having this issue, try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.
+### Missing libraries for React
 
-## Xcode Build Failures
+If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like `RCTText.xcodeproj`, `RCTImage.xcodeproj`. Next, the binaries built by these dependencies have to be linked to your app binary. Use the `Linked Frameworks and Binaries` section in the Xcode project settings. More detailed steps are here: [Linking Libraries](docs/linking-libraries-ios.html#content).
 
-To see the exact error that is causing your build to fail, go into the Issues Navigator in the left sidebar.
-
-##### React libraries missing
 If you are using CocoaPods, verify that you have added React along with the subspecs to the `Podfile`. For example, if you were using the `<Text />`, `<Image />` and `fetch()` APIs, you would need to add these in your `Podfile`:
+
 ```
 pod 'React', :path => '../node_modules/react-native', :subspecs => [
   'RCTText',
@@ -77,46 +59,31 @@ pod 'React', :path => '../node_modules/react-native', :subspecs => [
   'RCTWebSocket',
 ]
 ```
-Next, make sure you have run `pod install` and that a `Pods/` directory has been created in your project with React installed. CocoaPods will instruct you to use the generated `.xcworkspace` file henceforth to be able to use these installed dependencies.
 
-If you are adding React manually, make sure you have included all the relevant dependencies, like `RCTText.xcodeproj`, `RCTImage.xcodeproj` depending on the ones you are using. Next, the binaries built by these dependencies have to be linked to your app binary. Use the `Linked Frameworks and Binaries` section in the Xcode project settings. More detailed steps are here: [Linking Libraries](docs/linking-libraries-ios.html#content).
+Next, make sure you have run `pod install` and that a `Pods/` directory has been created in your project with React installed. CocoaPods will instruct you to use the generated `.xcworkspace` file henceforth to be able to use these installed dependencies.
 
-##### Argument list too long: recursive header expansion failed
+#### Argument list too long: recursive header expansion failed
 
 In the project's build settings, `User Search Header Paths` and `Header Search Paths` are two configs that specify where Xcode should look for `#import` header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.
 
 To revert the `User Search Header Paths` and `Header Search Paths` build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.
 
-## Unable to connect to development server
-
-##### iOS
-Ensure that you are on the same WiFi network as your computer. If you're using a cell data plan, your phone can't access your computer's local IP address.
-
-##### Android
-You need to run `adb reverse tcp:8081 tcp:8081` to forward requests from the device to your computer. This works only on Android 5.0 and newer.
+### No transports available
 
-## Module that uses `WebSocket` (such as Firebase) throws an exception
+React Native implements a polyfill for WebSockets. These [polyfills](https://github.com/facebook/react-native/blob/master/Libraries/JavaScriptAppEngine/Initialization/InitializeJavaScriptAppEngine.js) are initialized as part of the react-native module that you include in your application through `import React from 'react-native'`. If you load another module that requires WebSockets, such as [Firebase](https://github.com/facebook/react-native/issues/3645), be sure to load/require it after react-native:
 
-React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through `import React from 'react-native'`. If you load another module that requires WebSockets, be sure to load/require it after react-native.
-
-So:
 ```
 import React from 'react-native';
 import Firebase from 'firebase';
 ```
 
-Requiring firebase *before* react-native will result in a 'No transports available' redbox.
-
-Discovered thanks to issue [#3645](https://github.com/facebook/react-native/issues/3645). If you're curious, the polyfills are set up in [InitializeJavaScriptAppEngine.js](https://github.com/facebook/react-native/blob/master/Libraries/JavaScriptAppEngine/Initialization/InitializeJavaScriptAppEngine.js).
-
-
 ## Shell Command Unresponsive Exception
 
-If you encounter:
+If you encounter a ShellCommandUnresponsiveException exception such as:
 
 ```
 Execution failed for task ':app:installDebug'.
   com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException
 ```
 
-Try downgrading your Gradle version to 1.2.3 in `<project-name>/android/build.gradle` (https://github.com/facebook/react-native/issues/2720)
+Try [downgrading your Gradle version to 1.2.3](https://github.com/facebook/react-native/issues/2720) in `android/build.gradle`.