[Docs] Reorganize documentation

CONTRIBUTING.rst

@@ -252,41 +252,3 @@ To run these tests::
 
 For more information on how to run the ltp tests, please refer to
 :file:`libos/test/ltp/README.rst`.
-
-
-Management Team (Maintainers)
-=============================
-
-The currently active members of the management team are:
-
-* Michał Kowalczyk (Invisible Things Lab/Intel)
-* Dmitrii Kuvaiskii (Intel)
-* Borys Popławski (Invisible Things Lab/Intel)
-* Wojtek Porczyk (Invisible Things Lab/Intel)
-* Don Porter (UNC)
-* Kailun Qin (Intel)
-* Chia-Che Tsai (Texas A&M University)
-* Mona Vij (Intel)
-
-The past (inactive) members of the management team are:
-
-* Paweł Marczewski
-* Rafał Wojdyła
-* Isaku Yamahata
-
-The active members have the review and voting rights. The past (inactive)
-members have only the review rights.
-
-The active members are also the TSC voting members as described in the Technical
-Charter for Gramine project.
-
-The Procedure for Adding and Removing Maintainers
--------------------------------------------------
-
-+ Joining: # of PRs submitted & merged + # of PRs reviewed + # of issues closed
-  >= 20 (this means that a PR which fixes 3 issues counts as 4). Only complete
-  and thorough reviews count.
-+ Leaving: a member may be removed if not active or notoriously breaking rules
-  from this document.
-+ Additionally, at least 60% (rounded up) of currently active members have to
-  agree to make any change to the team membership.

Documentation/_static/css/gramine.css

@@ -1,3 +1,8 @@
 .rst-content dl:not(.docutils)>dt {
     font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
 }
+/* adds scrollbar to sidenav */
+.wy-side-scroll {
+    width: auto;
+    overflow-y: auto;
+  }

Documentation/concepts-index.rst

@@ -0,0 +1,7 @@
+Concepts
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   sgx-intro

Documentation/configuration-index.rst

@@ -0,0 +1,12 @@
+.. _index_configuration
+
+Configuration
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   manifest-syntax
+   attestation
+   performance
+   manpages/index.rst

Documentation/curated-installation.rst

@@ -0,0 +1,26 @@
+.. _curated_index
+
+Ready-made confidential protected images
+========================================
+
+.. note::
+    This is not an official part of Gramine.
+    The offering mentioned here wasn't thoroughly reviewed by the Gramine
+    maintainers.
+    Use at your own risk!
+
+Confidential Compute images with Gramine are ready-made solutions for popular
+open-source projects, such as PyTorch and Redis.
+Customize your environment through interactive scripts.
+The result is a curated, confidentially protected Gramine image that includes
+your specific machine-learning application, common dependencies, and a Gramine
+manifest file that specifies security policies to enforce for your workload.
+
+.. note::
+    These confidential compute images only run on machines that support Intel
+    SGX.
+
+Current list of solutions and installation instructions:
+
+- `Redis <https://github.com/gramineproject/contrib/tree/master/Intel-Confidential-Compute-for-X/workloads/redis>`_
+- `PyTorch <https://github.com/gramineproject/contrib/tree/master/Intel-Confidential-Compute-for-X/workloads/pytorch>`_

Documentation/devel/building.rst

@@ -1,5 +1,5 @@
-Building
-========
+Build and install Gramine from source
+=====================================
 
 .. highlight:: sh
 
@@ -10,19 +10,19 @@ Gramine consists of several components:
 - A patched C Library (shared library ``libc.so`` and possibly others).
   Currently there are two options: musl and GNU C Library (glibc).
 
-The build of Gramine implies building at least the first two components. The
+Building Gramine implies building at least the first two components. The
 build of the patched C library is optional but highly recommended for
 performance reasons. Both patched glibc and patched musl are built by default.
 
 Gramine currently only works on the x86_64 architecture. Gramine is currently
 tested on Ubuntu 18.04/20.04, along with Linux kernel version 5.x. We recommend
 building and installing Gramine on Ubuntu with Linux kernel version 5.11 or
-higher. If you find problems with Gramine on other Linux distributions, please
+higher. If you find problems with Gramine on other Linux distributions,
 contact us with a |~| detailed `bug report
 <https://github.com/gramineproject/gramine/issues/new>`__.
 
-Installing dependencies
------------------------
+Install dependencies
+--------------------
 
 .. _common-dependencies:
 
@@ -71,7 +71,7 @@ Kernel version can be checked using the following command::
 If your current kernel version is lower than 5.11, then you have two options:
 
 - Update the Linux kernel to at least 5.11 in your OS distro. If you use Ubuntu,
-  you can follow e.g. `this tutorial
+  you can follow e.g., `this tutorial
   <https://itsfoss.com/upgrade-linux-kernel-ubuntu/>`__.
 
 - Install out-of-tree driver and use our provided patches to the Linux kernel
@@ -116,10 +116,10 @@ If you plan on enabling ``-Ddcap`` option, you need to install
    sudo apt-get update
    sudo apt-get install libsgx-dcap-quote-verify-dev
 
-Building
---------
+Build Gramine
+-------------
 
-In order to build Gramine, you need to first set up the build directory. In the
+To build Gramine, you need to first set up the build directory. In the
 root directory of Gramine repo, run the following command (recall that "direct"
 means non-SGX version)::
 
@@ -250,7 +250,7 @@ Additional build options
 
   .. _POSIX.1-2018 8.3: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03
 
-  This very much depends on particular distribution, so please consult relevant
+  This very much depends on a particular distribution, so please consult relevant
   documentation provided by your distro.
 
 - To compile a patched version of GCC's OpenMP library (``libgomp``), install
@@ -268,14 +268,14 @@ Additional build options
 Prepare a signing key
 ---------------------
 
-Only for SGX enclave development, and if you haven't already, run the following
-command::
+These instructions are only required for systems using Intel® SGX that have not
+already created a signing key.
 
-   gramine-sgx-gen-private-key
+The following command generates an |~| RSA 3072 key suitable for signing SGX
+enclaves and stores it in :file:`{HOME}/.config/gramine/enclave-key.pem`.
+Protect this key and do not disclose it to anyone::
 
-This command generates an |~| RSA 3072 key suitable for signing SGX enclaves and
-stores it in :file:`{HOME}/.config/gramine/enclave-key.pem`. This key needs to
-be protected and should not be disclosed to anyone.
+   gramine-sgx-gen-private-key
 
 After signing the application's manifest, users may ship the application and
 Gramine binaries, along with an SGX-specific manifest (``.manifest.sgx``
@@ -361,6 +361,7 @@ FSGSBASE patchset was merged in Linux kernel version 5.9, so if your kernel
 version is 5.9 or higher, then the FSGSBASE feature is already supported and you
 can skip this step. For older kernels it is available as `separate patches
 <https://github.com/oscarlab/graphene-sgx-driver/tree/master/fsgsbase_patches>`__.
+
 (Note that Gramine was prevously called *Graphene* and was hosted under
 a different organization, hence the name of the linked repository.)
 

Documentation/devel/coding-style.rst

@@ -2,7 +2,7 @@ Coding style guidelines
 =======================
 
 This document describes coding conventions and formatting styles we use in
-Gramine. All newly commited code must conform to them to pass a |~| review.
+Gramine. All newly committed code must conform to them to pass a |~| review.
 
 Automatic reformatting
 ----------------------

Documentation/devel/debugging.rst

@@ -54,7 +54,7 @@ Compiling with optimizations enabled
 ------------------------------------
 
 Building Gramine with ``--buildtype=debug`` enables debug symbols and GDB
-integration, but disables optimizations. This is usually the right thing to do:
+integration but disables optimizations. This is usually the right thing to do:
 optimized builds are harder to debug, as they may cause GDB to display confusing
 tracebacks or garbage data.
 

Documentation/docker-image-installation.rst

@@ -0,0 +1,33 @@
+Gramine Docker image
+====================
+
+This Gramine image is a minimal distribution of Gramine: it contains only
+Gramine binaries and tools, as well as the pre-requisite packages to run
+applications under Gramine. The only currently available Gramine image is based
+on Ubuntu 20.04. The only requirement on the host system is a Linux kernel with
+in-kernel SGX driver (available from version 5.11 onward).
+
+This Gramine image can be used as a disposable playground environment, to
+quickly test Gramine with your applications and workloads. This image can also
+be used as a base for your workflows to produce production-ready Docker images
+for your SGX applications.
+
+The Gramine team publishes a base Gramine Docker image at:
+`DockerHub <https://hub.docker.com/r/gramineproject/gramine>`_.
+
+To run the Gramine image via Docker, the recommended command is::
+
+    docker run --device /dev/sgx_enclave -it gramineproject/gramine
+
+If you want to run :program:`gramine-direct` in addition to
+command:`gramine-sgx`, then you should run Docker with our custom seccomp
+profile using::
+
+    --security-opt seccomp=<profile_file>
+
+You can download the profile file from:
+https://github.com/gramineproject/gramine/blob/master/scripts/docker_seccomp.json.
+
+Alternatively you can disable seccomp completely::
+
+    --security-optseccomp=unconfined

Documentation/environment-setup.rst

@@ -0,0 +1,40 @@
+.. _environment_setup
+
+Set up the Gramine environment
+------------------------------
+
+Gramine without SGX has no special requirements.
+
+Gramine with SGX support requires several features from your system:
+
+- The FSGSBASE feature of recent processors must be enabled in the Linux kernel.
+- The Intel SGX driver must be built in the Linux kernel.
+- The Intel PSW must be installed.
+- The Intel DCAP must be installed if DCAP-based attestation should be used.
+
+If your system doesn’t meet these requirements, please refer to more detailed
+descriptions in :doc:`devel/building`.
+
+Check for SGX compatibility
+===========================
+
+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’s installed together with the respective gramine package you previously
+installed.
+
+Prepare a signing key
+=====================
+
+.. highlight:: sh
+
+Only for SGX, and if you haven’t already, enter the following:
+
+::
+
+    gramine-sgx-gen-private-key
+
+This command generates an RSA 3072 key suitable for signing SGX enclaves and
+stores it in :file:`{HOME}/.config/gramine/enclave-key.pem`.
+Protect this key and do not disclose it to anyone.

Documentation/gsc-installation.rst

@@ -0,0 +1,20 @@
+Gramine Shielded Containers
+===========================
+
+The Gramine Shielded Container (GSC) tool transforms an original Docker image
+into a new, "graminized" image which includes the Gramine Library OS, manifest
+files, and Intel SGX related information.
+It uses Gramine to execute the application inside an Intel SGX enclave.
+It follows the common Docker approach to first build an image and subsequently
+run this image inside a container.
+
+At first a Docker image has to be graminized via the ``gsc build`` command.
+When the graminized image is run within an Intel SGX enclave, the image must be
+signed via a ``gsc sign-image`` command.
+Subsequently, the image can be run using ``docker run``.
+
+Note the GSC documentation is split from the core Gramine documentation
+and is hosted here: https://gramine.readthedocs.io/projects/gsc.
+
+Similarly, the GSC tool is split from the core Gramine repository and can be
+found here: https://github.com/gramineproject/gsc.