Add mobile device guide

docs/howtos/index.rst

@@ -15,3 +15,4 @@ These guides are step by step guides for common tasks in getting started and wor
   rebasing_a_pull_request
   another_kolibri_instance
   development_with_kds
+  preview_on_mobile

docs/howtos/preview_on_mobile.md

@@ -0,0 +1,48 @@
+# Preview Kolibri on a mobile device
+
+_Note: This guide focuses on Kolibri as a web app rather than the Android version of Kolibri._
+
+Some tasks may require either an actual or simulated mobile device, such as a phone or tablet.
+
+## Browser development tools
+
+Most browsers provide ways to simulate mobile devices via their development tools. These tools are generally useful for testing:
+
+- Mobile viewports
+- Network and CPU throttling
+- Touch gestures
+
+Find specific guidance for the browser you are using.
+
+## Real mobile device
+
+Since browser development tools only offer an approximation, some tasks may require you to preview Kolibri on a real mobile device.
+
+### Option 1 (recommended)
+
+1. Ensure that the mobile device you wish to use for previewing Kolibri is connected to the same local network as your computer where you run the development server.
+2. Run the development server with `yarn python-devserver` and `yarn run watch --write-to-disk`
+3. Find your computer's IP address
+4. Open a browser on the mobile device and navigate to your computer's IP address with port `:8000`, `http://x.x.x.x:8000`. There, you should see Kolibri.
+
+.. tip::
+   In ``yarn run watch --write-to-disk`` command terminal output, you can find your computer's IP address on the line ``[webpack-dev-server] On Your Network (IPv4): http://x.x.x.x:3000/``.
+
+### Option 2
+
+1. Ensure that the mobile device you wish to use for previewing Kolibri is connected to the same local network as your computer where you run the development server.
+2. Run the development server with `yarn python-devserver` and `yarn build`
+3. Find your computer's IP address
+4. Open a browser on the mobile device and navigate to your computer's IP address with port `:8000`, `http://x.x.x.x:8000`. There, you should see Kolibri.
+
+.. warning::
+   When running the development server as described above, you will need to rebuild frontend assets manually using ``yarn build`` after every change.
+
+.. tip::
+   Rebuild frontend assets faster by rebuilding only assets related to a plugin where you currently work. For example when developing on files of the Learn plugin, after the initial ``yarn build`` run, for all subsequent rebuilds only run ``yarn exec kolibri-tools build prod -- --plugins kolibri.plugins.learn`` instead of ``yarn build``. Use ``kolibri plugin list`` to see all plugins.
+
+### Troubleshooting
+
+- If you see an indefinite Kolibri loader on your mobile device, double-check that you are not running the development server with `yarn development-hot`. Follow the steps outlined above instead.
+
+- If you cannot access Kolibri at all, check your firewall, VPN, or similar network settings.