Merge pull request #335 from hypothesis/convert-mobile-docs-to-rst

Use Sphinx environment variable cross-references

docs/Makefile

@@ -15,7 +15,7 @@ help:
 .PHONY: help Makefile
 
 livehtml:
-	sphinx-autobuild -b dirhtml -p 8888 "$(SOURCEDIR)" "$(BUILDDIR)/dirhtml" $(SPHINXOPTS) $(O)
+	sphinx-autobuild -n -b dirhtml -p 8888 "$(SOURCEDIR)" "$(BUILDDIR)/dirhtml" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/developers/envvars.rst

@@ -8,3 +8,7 @@ build tasks.
 
    The URL of the service which hosts the HTML entry point for the client's
    sidebar application.
+
+.. envvar:: PACKAGE_SERVER_HOSTNAME
+
+   The hostname that is used to generate URLs to the package content server.

docs/developers/mobile.md

-# Mobile Development
-
-## Testing the Client on a Mobile Device
-
-If you have made changes to the client that could affect the mobile experience, it is a good idea to test them on a real device. Such changes should ideally be tested with at least current versions of iOS Safari and Chrome for Android.
-
-1. Make sure your development system and mobile device are on the same local network.
-1. Configure the "h" service to allow incoming connections from other systems by editing `conf/development-app.ini` and changing the `host` setting from `localhost` to `0.0.0.0`.
-1. Get the IP address or host name of your development system (`<HOSTNAME>` in the steps below). You can do this using the `hostname` terminal command on Mac/Linux.
-
-   **Tip:** _If the output of `hostname` does not include a `.home` or `.local`
-   suffix, you may need to append `.local` to get a host name that is accessible from
-   other devices on the network. If you have problems using the host name, try
-   using the IP address instead._
-1. Configure the "h" service to load the client from this host and start the dev
-   server:
-   ```sh
-   # In the "h" repository
-
-   # Configure the URL that the client is loaded from in pages
-   # that embed Hypothesis
-   export CLIENT_URL=http://<HOSTNAME>:3001/hypothesis
-
-   make dev
-   ```
-1. Configure the client to load assets from this hostname and start the dev
-   server:
-   ```sh
-   # In the "client" repository
-
-   # Set URL which sidebar app ("app.html") is loaded from
-   export H_SERVICE_URL=http://<HOSTNAME>:5000
-   # Set hostname used when generating client asset URLs
-   export PACKAGE_SERVER_HOSTNAME=<HOSTNAME>
-
-   gulp watch
-   ```
-   **Tip:** _When `gulp watch` runs, it will print out the URLs used for the "h" service and client assets. These should include `<HOSTNAME>` instead of `localhost`._
-1. On your mobile device, go to a page which has the client embedded such as `http://<HOSTNAME>:3000` or `http://<HOSTNAME>:5000/docs/help`.

docs/developers/mobile.rst

+Mobile Development
+==================
+
+Testing the Client on a Mobile Device
+-------------------------------------
+
+If you have made changes to the client that could affect the mobile experience,
+it is a good idea to test them on a real device. Such changes should ideally be
+tested with at least current versions of iOS Safari and Chrome for Android.
+
+#. Make sure your development system and mobile device are on the same local
+   network.
+
+#. Configure h to allow incoming connections from other systems
+   by editing ``conf/development-app.ini`` and changing the ``host`` setting from
+   ``localhost`` to ``0.0.0.0``.
+
+#. Get the IP address or hostname of your development system (``<HOSTNAME>``
+   in the steps below). You can do this using the ``hostname`` terminal command on
+   Mac/Linux.
+
+   .. tip::
+
+      If the output of ``hostname`` does not include a ``.home`` or ``.local``
+      suffix, you may need to append ``.local`` to get a hostname that is
+      accessible from other devices on the network. If you have problems using
+      the hostname, try using the IP address instead.
+
+#. Set the :envvar:`CLIENT_URL` environment variable to configure h
+   to load the client from this host and start the dev server:
+
+   .. code-block:: sh
+
+      # In the h repository
+
+      # Configure the URL that the client is loaded from in pages
+      # that embed Hypothesis
+      export CLIENT_URL=http://<HOSTNAME>:3001/hypothesis
+
+      make dev
+
+#. Set the :envvar:`H_SERVICE_URL` and :envvar:`PACKAGE_SERVER_HOSTNAME`
+   environment variables to load assets from this hostname and start the dev
+   server:
+
+   .. code-block:: sh
+
+      # In the client repository
+
+      # Set URL which sidebar app ("app.html") is loaded from
+      export H_SERVICE_URL=http://<HOSTNAME>:5000
+      # Set hostname used when generating client asset URLs
+      export PACKAGE_SERVER_HOSTNAME=<HOSTNAME>
+
+      gulp watch
+
+   .. tip::
+
+      When ``gulp watch`` runs, it will print out the URLs used for h
+      and client assets. These should include ``<HOSTNAME>`` instead of
+      ``localhost``.
+
+#. On your mobile device, go to a page which has the client embedded such as
+   ``http://<HOSTNAME>:3000`` or ``http://<HOSTNAME>:5000/docs/help``.