diff --git a/README.rst b/README.rst index 3b1f590e081fe9afa3eed8a02b97def1a2ea37a5..f789130688cce2d1e96015641540daad1076df77 100644 --- a/README.rst +++ b/README.rst @@ -1,60 +1,20 @@ PrivateStorageio ================ -The backend for a private, secure, and end-to-end encrypted storage solution - -Building --------- - -The build system uses `Nix`_ which must be installed before anything can be built. -Start by setting up the development/operations environment:: - - $ nix-shell +The backend for a private, secure, and end-to-end encrypted storage solution. Documentation ~~~~~~~~~~~~~ +There is documentation for: + +* Users: ``docs/user/README.rst`` +* Operators/Admins: ``docs/ops/README.rst`` +* Developers: ``docs/dev/README.rst`` + The documentation can be built using this command:: $ nix-build docs.nix The documentation is also built on and published by CI. -Testing -------- - -The test system uses `Nix`_ which must be installed before any tests can be run. - -Unit tests are run using this command:: - - $ nix-build nixos/unit-tests.nix - -Unit tests are also run on CI. - -The system tests are run using this command:: - - $ sudo --preserve-env nix-build nixos/system-tests.nix - -The system tests boot QEMU VMs which prevents them from running on CI at this time. -Starting VMs require elevated privileges, -which is the reason for the suggested ``sudo`` command, -together with the ``--preserve-env`` option to avoid escaping the ``nix-shell`` set up at the top. -The build requires > 10 GB of disk space, -and the VMs might be timing out on slow or busy machines. -If you run into timeouts, -try `raising the number of retries <https://github.com/PrivateStorageio/PrivateStorageio/blob/e8233d2/nixos/modules/tests/run-introducer.py#L55-L62>`_. - -It is also possible go through the testing script interactively - useful for debugging:: - - $ sudo --preserve-env nix-build -A private-storage.driver nixos/system-tests.nix - -This will give you a result symlink in the current directory. -Inside that is bin/nixos-test-driver which gives you a kind of REPL for interacting with the VMs. -The kind of `Perl in this testScript <https://github.com/PrivateStorageio/PrivateStorageio/blob/78881a3/nixos/modules/tests/private-storage.nix#L180>`_ is what you can enter into this REPL. - -Deployment ----------- - -See ``morph/README.rst``. - -.. _Nix: https://nixos.org/nix diff --git a/docs/source/README.rst b/docs/source/README.rst deleted file mode 100644 index 068656ccfbf7aabee907d6ffb3ac28c37415f7b7..0000000000000000000000000000000000000000 --- a/docs/source/README.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: - ../../README.rst diff --git a/docs/source/architecture-overview.rst b/docs/source/architecture-overview.rst deleted file mode 100644 index d8480a2483ebab1585287537f06b5a08664300d4..0000000000000000000000000000000000000000 --- a/docs/source/architecture-overview.rst +++ /dev/null @@ -1,4 +0,0 @@ -Architecture Overview -===================== - -.. graphviz:: architecture-overview.dot diff --git a/docs/source/dev/README.rst b/docs/source/dev/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..117915f62ab9d34fb7d8c5ba8a150f50246fc704 --- /dev/null +++ b/docs/source/dev/README.rst @@ -0,0 +1,51 @@ +Developer documentation +======================= + +Building +-------- + +The build system uses `Nix`_ which must be installed before anything can be built. +Start by setting up the development/operations environment:: + + $ nix-shell + +Testing +------- + +The test system uses `Nix`_ which must be installed before any tests can be run. + +Unit tests are run using this command:: + + $ nix-build nixos/unit-tests.nix + +Unit tests are also run on CI. + +The system tests are run using this command:: + + $ sudo --preserve-env nix-build nixos/system-tests.nix + +The system tests boot QEMU VMs which prevents them from running on CI at this time. +Starting VMs require elevated privileges, +which is the reason for the suggested ``sudo`` command, +together with the ``--preserve-env`` option to avoid escaping the ``nix-shell`` set up at the top. +The build requires > 10 GB of disk space, +and the VMs might be timing out on slow or busy machines. +If you run into timeouts, +try `raising the number of retries <https://github.com/PrivateStorageio/PrivateStorageio/blob/e8233d2/nixos/modules/tests/run-introducer.py#L55-L62>`_. + +It is also possible go through the testing script interactively - useful for debugging:: + + $ sudo --preserve-env nix-build -A private-storage.driver nixos/system-tests.nix + +This will give you a result symlink in the current directory. +Inside that is bin/nixos-test-driver which gives you a kind of REPL for interacting with the VMs. +The kind of `Perl in this testScript <https://github.com/PrivateStorageio/PrivateStorageio/blob/78881a3/nixos/modules/tests/private-storage.nix#L180>`_ is what you can enter into this REPL. + +Architecture overview +--------------------- + +.. graphviz:: architecture-overview.dot + + +.. _Nix: https://nixos.org/nix + diff --git a/docs/source/architecture-overview.dot b/docs/source/dev/architecture-overview.dot similarity index 100% rename from docs/source/architecture-overview.dot rename to docs/source/dev/architecture-overview.dot diff --git a/docs/source/index.rst b/docs/source/index.rst index 8cc638a205fcdf6723cf0d48ca4e258dadb00fce..aa38cfd14a28a782f219d95847ac099c9e6e8fb5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,13 +6,14 @@ Welcome to PrivateStorageio's documentation! ============================================ +Howdy! We separated the documentation into parts addressing different audiences. Please enjoy our docs for: + .. toctree:: :maxdepth: 2 - :caption: Contents: - README - architecture-overview - morph + Users <user/README> + Administrators <ops/README> + Developers <dev/README> diff --git a/docs/source/morph.rst b/docs/source/morph.rst deleted file mode 100644 index 5bcffb5fb5a6928a69300dcfb3ac4cb7126ba09a..0000000000000000000000000000000000000000 --- a/docs/source/morph.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: - ../../morph/README.rst diff --git a/docs/source/ops/README.rst b/docs/source/ops/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..22b53e6590d9564a4635c03dc3cd6fd8b982c5cc --- /dev/null +++ b/docs/source/ops/README.rst @@ -0,0 +1,9 @@ +Adminstrator documentation +========================== + +This contains documentation regarding running PrivateStorageIo. + +.. include:: + ../../../morph/README.rst + :start-line: 9 + diff --git a/docs/source/user/README.rst b/docs/source/user/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..2a6e4b912cb6dfafb250149eb8aab095c34ce023 --- /dev/null +++ b/docs/source/user/README.rst @@ -0,0 +1,5 @@ +User documentation +================== + +This will contain the user documentation for this project. +