[Docs] Minor updates and rearrangements

- Add Troubleshooting section in "Run a sample application" page.
- Rearrange build instruction paragraphs in "Build Gramine" section.
- Add Installation Prerequisites in "Building documentation" section.

Signed-off-by: Erica Fu <ericafu@cs.unc.edu>

Documentation/devel/building.rst

@@ -58,12 +58,12 @@ GCC's build dependencies::
 Dependencies for SGX
 ^^^^^^^^^^^^^^^^^^^^
 
-The build of Gramine with SGX support requires the corresponding SGX software
-infrastructure to be installed on the system. We require Linux kernel with SGX
-driver built in (``CONFIG_X86_SGX=y``, which is the case for most of available
-distribution kernels), which is available since version 5.11 (and also as
-backported patches to older kernels in certain distros). Note this requires CPU
-with :term:`FLC`.
+The build of Gramine with SGX support requires CPU with :term:`Flexible Launch
+Control (FLC)<FLC>` feature and the corresponding SGX software infrastructure to
+be installed on the system. We require Linux kernel with SGX driver built in
+(``CONFIG_X86_SGX=y``, which is the case for most of available distribution
+kernels), which is available since version 5.11 (and also as backported patches
+to older kernels in certain distros).
 
 Kernel version can be checked using the following command::
 
@@ -126,7 +126,7 @@ directory of Gramine repo, run the following command (recall that "direct" means
 non-SGX version)::
 
    meson setup build/ --buildtype=release -Ddirect=enabled -Dsgx=enabled \
-       -Dsgx_driver=<driver> -Dsgx_driver_include_path=<path-to-sgx-driver-sources>
+       -Dsgx_driver=(upstream|oot) -Dsgx_driver_include_path=<path-to-sgx-driver-sources>
 
 .. note::
 
@@ -141,11 +141,6 @@ non-SGX version)::
    -Dsgx=disabled`` first and now want to enable SGX, type ``meson configure
    build/ -Dsgx=enabled``.
 
-Then, build and install Gramine by running the following::
-
-   ninja -C build/
-   sudo ninja -C build/ install
-
 Set ``-Ddirect=`` and ``-Dsgx=`` options to ``enabled`` or ``disabled``
 according to whether you built the corresponding PAL (the snippet assumes you
 built both).
@@ -174,6 +169,11 @@ Set ``-Dlibc`` option to ``musl`` if you wish to build musl instead of glibc
 (which is built by default), or to ``none`` if you do not want to build any
 libc.
 
+Then, build and install Gramine by running the following::
+
+   ninja -C build/
+   sudo ninja -C build/ install
+
 Installation prefix
 ^^^^^^^^^^^^^^^^^^^
 

Documentation/devel/howto-doc.rst

@@ -38,15 +38,13 @@ not published.
    When launched through ``make`` (like ``make -C Documentation html``), this
    becomes "target" in Make terminology.
 
-Building documentation
-----------------------
-
-To build documentation, change directory to ``Documentation``, install prerequisites, and use
-``make``, specifying the appropriate target. The documentation is built with python3; if you have
-similar packages in python2, it may create problems; we recommend removing any similar packages in
-python2. Similarly, the documentation requires version 1.8 of sphinx.
+Installing prerequisites
+------------------------
 
-The output is in the ``_build`` directory:
+Change directory to ``Documentation``, install prerequisites including Doxygen,
+Breathe and Sphinx. Gramine documentation requires version 1.8 of Sphinx. The
+documentation is built with python3; if you have similar packages in python2, it
+may create problems; we recommend removing any similar packages in python2.
 
 .. code-block:: sh
 
@@ -57,6 +55,14 @@ The output is in the ``_build`` directory:
    sudo apt-get install doxygen
    python3 -m pip install -r requirements.txt
 
+Building documentation
+----------------------
+
+Execute ``make`` command in ``Documentation`` directory, specifying the
+appropriate target. The output is in the ``_build`` directory.
+
+.. code-block:: sh
+
    # build targets "html" and "man"
    make html man
 

Documentation/run-sample-application.rst

@@ -12,15 +12,25 @@ installation. To clone the Gramine repo, use the following command:
 
 Don't build Gramine if it is already installed on the system.
 
+Prerequisite
+------------
+
+Please refer to :doc:`sgx-setup` section to set up the host environment.
+
 Build and run HelloWorld sample app
 -----------------------------------
 
 To build the HelloWorld application, install the ``gcc`` compiler and the
-``make`` build system by entering the following::
+``make`` build system by entering one of the following::
+
+   # for Ubuntu distribution
+   sudo apt-get install gcc make
 
-   sudo apt-get install gcc make  # for Ubuntu distribution
-   sudo dnf install gcc make      # for RHEL-like distribution
-   sudo apk add build-base make   # for Alpine distribution
+   # for RHEL-like distribution
+   sudo dnf install gcc make
+
+   # for Alpine distribution
+   sudo apk add build-base make
 
 Go to the HelloWorld example directory::
 
@@ -41,6 +51,26 @@ If you want to run this example on Alpine, then before building, modify the
 ``gramine.runtimedir('musl')``. For details, see the section "glibc vs musl"
 below.
 
+Troubleshooting
+^^^^^^^^^^^^^^^
+
+- **"Signing key does not exist" error**
+
+If the following error occurs, please refer to :ref:`prepare-a-signing-key`
+section to prepare a key if you haven't done so::
+
+   $ make SGX=1
+   Error: Invalid value for "--key" / "-k": File "~/.config/gramine/enclave-key.pem" does not exist.
+   make: *** [Makefile:44: sgx_sign] Error 2
+
+- **"Cannot open SGX driver device" error**
+
+If the following error occurs, please refer to :doc:`sgx-setup` section to check
+the system environment for SGX compatibility::
+
+   $ gramine-sgx helloworld
+   error: Cannot open SGX driver device.  [...]
+
 Other sample applications
 -------------------------
 

Documentation/sgx-setup.rst

@@ -25,6 +25,8 @@ We supply a tool, :doc:`manpages/is-sgx-available` that checks the environment
 for SGX compatibility. Use this tool to check your hardware and system. It is
 installed together with the Gramine package.
 
+.. _prepare-a-signing-key:
+
 Prepare a signing key
 ---------------------