Merge pull request #631 from Szymongib/fix/minor-docs-fixes

Fix some typos and align formatting

crates/libcgroups/src/common.rs

@@ -38,13 +38,13 @@ pub trait CgroupManager {
     /// Removes the cgroup
     fn remove(&self) -> Result<()>;
 
-    // Sets the freezer cgroup to the specified state
+    /// Sets the freezer cgroup to the specified state
     fn freeze(&self, state: FreezerState) -> Result<()>;
 
     /// Retrieve statistics for the cgroup
     fn stats(&self) -> Result<Stats>;
 
-    // Gets the PIDs inside the cgroup
+    /// Gets the PIDs inside the cgroup
     fn get_all_pids(&self) -> Result<Vec<Pid>>;
 }
 

crates/libcgroups/src/stats.rs

@@ -240,7 +240,7 @@ pub fn parse_single_value(file_path: &Path) -> Result<u64> {
     })
 }
 
-/// Parses a file that is structed according to the flat keyed format
+/// Parses a file that is structured according to the flat keyed format
 pub fn parse_flat_keyed_data(file_path: &Path) -> Result<HashMap<String, u64>> {
     let mut stats = HashMap::new();
     let keyed_data = common::read_cgroup_file(file_path)?;

docs/src/developer/basics.md

@@ -12,7 +12,7 @@ Before you start working on developing youki, you should go through [the User do
 
 #### OCI
 
-Open containers initiative is project, which provides a standardization and standardized specification for operating-system-level virtualization. That way components that confirm to the specification provided by OCI spec, can interoperate with each other easily, and developing of new applications becomes easier. For example youuki can be used inplace of runc in Docker, as all three : Docker, runc and youki are OCI compliant, and have a standard interface.
+Open containers initiative is project, which provides a standardization and standardized specification for operating-system-level virtualization. That way components that confirm to the specification provided by OCI spec, can interoperate with each other easily, and developing of new applications becomes easier. For example youki can be used inplace of runc in Docker, as all three : Docker, runc and youki are OCI compliant, and have a standard interface.
 
 Their main GitHub page is at [https://github.com/opencontainers](https://github.com/opencontainers), and more information about the runtime specifications can be found at [https://github.com/opencontainers/runtime-spec/blob/master/runtime.md](https://github.com/opencontainers/runtime-spec/blob/master/runtime.md).
 

docs/src/developer/crate_specific_information.md

@@ -1,5 +1,5 @@
 # Crate Specific Information
 
-This section contains sub-sections for each individual crate in the youki workspace. Each of the seb-section will have information and resources on that particular crate.
+This section contains subsections for each individual crate in the youki workspace. Each of the subsection will have information and resources on that particular crate.
 
 In case you are working with some specific crate, you can find resources about it in its section. Also make sure you add any resources that you find when working on them as well.

docs/src/developer/good_places_to_start.md

@@ -4,7 +4,7 @@ First of all, welcome to youki! Hope you have fun while developing and contribut
 
 This lists some of the known places that are long-running and would be useful for beginners. But as the things under development can change any time, the best place to check are the issues on the [GitHub repo](https://github.com/containers/youki/issues). You can find issues with labels `good fist issue` or `help wanted` and start working on them.
 
-You can also search for `TODO` or `FIXME` comments in the source, and try working on them, but not all of them are easy places to start, can some of them can be particularly tricky to fix.
+You can also search for `TODO` or `FIXME` comments in the source, and try working on them, but not all of them are easy places to start, and some of them can be particularly tricky to fix.
 
 ---
 
@@ -14,10 +14,10 @@ This lists known parts of youki that can be good for beginners at the time of th
 
 Currently youki is decently commented, and those explain most of the public facing API and structs. But there are still places which can use more doc comments, and examples showing usage, so people can use the docs generated by `cargo doc` as a guide.
 
-If you don't know much about container runtime or low level system working, then this can be a good place to start. While going through the code an documenting it, you can learn about it. Make sure that you update this documentation with useful links that you found while commenting some code if it has some peculiar behavior, or it is hard to understand without knowing some background.
+If you don't know much about container runtime or low level system working, then this can be a good place to start. While going through the code and documenting it, you can learn about it. Make sure that you update this documentation with useful links that you found while commenting some code if it has some peculiar behavior, or it is hard to understand without knowing some background.
 
 #### Integration Tests
 
-You can find more detailed information about this in the integration_test crate, but in brief, we currently use [OCI-runtime-tools](https://github.com/opencontainers/runtime-tools) provided integration tests to validate that youki is OCI spec compliant. But those are written in Go, which makes the developer depend on two language env to compile youki and test it. These tests also have some issues which makes them hard to use on some system setups.
+You can find more detailed information about this in the `integration_test` crate, but in brief, we currently use [OCI-runtime-tools](https://github.com/opencontainers/runtime-tools) provided integration tests to validate that youki is OCI spec compliant. But those are written in Go, which makes the developer depend on two language env to compile youki and test it. These tests also have some issues which makes them hard to use on some system setups.
 
-Thus we are porting those test to Rust, so that it can be an Rust implementation of OCI-runtime integration tests, as well as be easy to run on local systems for testing. If you know Go and Rust this can be a great place to start. Check out the [tracking issue](https://github.com/containers/youki/issues/361).
+Thus we are porting those test to Rust, so that it can be a Rust implementation of OCI-runtime integration tests, as well as be easy to run on local systems for testing. If you know Go and Rust this can be a great place to start. Check out the [tracking issue](https://github.com/containers/youki/issues/361).

docs/src/developer/integration_test.md

@@ -12,11 +12,11 @@ As these tests are under development, these are validated on a standard runtime
 
 ### About the create container function
 
-The test_utils provides a create_container function which can be used to run the `youki create` command. It returns the child process struct, which can be either `wait()` or `wait_with_output()` to wait for it finishing. Unless you know what are you doing, it is recommended to call `wait()` on it, as otherwise the process will hang. As explained in the [youki docs](../youki.md) , the `youki create` process, after starting forks, and the forked process keeps waiting for another youki process to send it the `start` signal , and after receiving it, that forked process execs the container program. If you are simply trying to create a container, such as in case of `test_outside_runtime` then calling `wait_with_output()` will cause it to hand. If you are actually going to start a container, and need output from the container process, then you must keep the `Child struct` returned by `create` function and call `wait_with_output()` on it **AFTER** you have called the start command on that container, which will give you the `stdout` and `stderr` of the process running inside the container.
+The test_utils provides a `create_container` function which can be used to run the `youki create` command. It returns the child process struct, which can be either `wait()` or `wait_with_output()` to wait for it finishing. Unless you know what are you doing, it is recommended to call `wait()` on it, as otherwise the process will hang. As explained in the [youki docs](../youki.md) , the `youki create` process, after starting forks, and the forked process keeps waiting for another youki process to send it the `start` signal , and after receiving it, that forked process execs the container program. If you are simply trying to create a container, such as in case of `test_outside_runtime` then calling `wait_with_output()` will cause it to hang. If you are actually going to start a container, and need output from the container process, then you must keep the `Child struct` returned by `create` function and call `wait_with_output()` on it **AFTER** you have called the start command on that container, which will give you the `stdout` and `stderr` of the process running inside the container.
 
-To understand how this works, take a look at [handling stdio](https://github.com/opencontainers/runc/blob/master/docs/terminals.md) of the runc, specially the [detached pass-through mode](https://github.com/opencontainers/runc/blob/master/docs/terminals.md#detached-pass-through) section. As explained in it, we setup the stdio for the original youki process in `youki create` by setting the stdio to `Stdio::piped()` in the `create` function. then we set the `terminal` option to `false` (which is the default anyways) in the spec, which makes it run in the pass-through mode. Then when the create process is done its work, and its forked process is waiting for the start signal, it uses the same stdio pipes. Thus calling `wait_with_output()` without starting will keep it hanged up, and after calling start, stdio of the program to be run inside the container can be obtained from the `youki create`'s process.
+To understand how this works, take a look at [handling stdio](https://github.com/opencontainers/runc/blob/master/docs/terminals.md) of the runc, specially the [detached pass-through mode](https://github.com/opencontainers/runc/blob/master/docs/terminals.md#detached-pass-through) section. As explained in it, we setup the stdio for the original youki process in `youki create` by setting the stdio to `Stdio::piped()` in the `create` function. Then we set the `terminal` option to `false` (which is the default anyway) in the spec, which makes it run in the pass-through mode. Then when the create process is done its work, and its forked process is waiting for the start signal, it uses the same stdio pipes. Thus calling `wait_with_output()` without starting will keep it hanged up, and after calling start, stdio of the program to be run inside the container can be obtained from the `youki create`'s process.
 
 ### How test inside container works
 
-We use test_inside_container for making sure that the restrictions and constraints are uphold from inside the container process.
-For that, first whichever integration test needs to use it, must define the runtimetest as the container process in the spec, and then use `test_inside_container` function. It requires a function which will do the necessary setup for the tests that are to be run inside. Then the counterpart for the test should be added to the `runtimetest` crate, which will run inside the container and and if there is any error, print it to the `stderr`. The `test_inside_container` function will wait for the tests to be over and then check the `stderr` to be empty. If it is not, the the test is assumed to fail.
+We use `test_inside_container` for making sure that the restrictions and constraints are uphold from inside the container process.
+For that, first whichever integration test needs to use it, must define the runtimetest as the container process in the spec, and then use `test_inside_container` function. It requires a function which will do the necessary setup for the tests that are to be run inside. Then the counterpart for the test should be added to the `runtimetest` crate, which will run inside the container and if there is any error, print it to the `stderr`. The `test_inside_container` function will wait for the tests to be over and then check the `stderr` to be empty. If it is not, the test is assumed to fail.

docs/src/developer/libcgroups.md

@@ -6,9 +6,9 @@ The initial version of cgroups is called the version 1 was implemented in kernel
 
 This crates exposes several functions and modules that can be used to work with cgroups :
 
-- common traits and functions which are used by both v1 and v2 such as
+- Common traits and functions which are used by both v1 and v2 such as
 
-  - Trait CgroupManager, this abstracts over the underlying implementation of interacting with specific version of cgroups, and gives functions to add certain process to a certain cgroup, apply resource restrictions, get statistics of a cgroups, freeze a cgroup, remove a cgroup or get list of all processes belonging to a cgroup. v1 and v2 modules both contain a version specific cgroup manager which implements this trait, and thus either can be given to functions or structs which expects a cgroup manager, depending on which cgroups the host system uses.
+  - Trait `CgroupManager`, this abstracts over the underlying implementation of interacting with specific version of cgroups, and gives functions to add certain process to a certain cgroup, apply resource restrictions, get statistics of a cgroups, freeze a cgroup, remove a cgroup or get list of all processes belonging to a cgroup. v1 and v2 modules both contain a version specific cgroup manager which implements this trait, and thus either can be given to functions or structs which expects a cgroup manager, depending on which cgroups the host system uses.
   - Apart from the trait, this also contains functions which help with reading cgroups files, and write data to a cgroup file, which are used throughout this crate.
   - A function to detect which cgroup setup (v1, v2 or hybrid) is on the host system, as well as a function to get the corresponding cgroups manager.
 

docs/src/developer/libcontainer.md

@@ -28,7 +28,7 @@ This crate also provides an interface for Apparmor which is another Linux Kernel
 - [pid namespace man page](https://man7.org/linux/man-pages/man7/pid_namespaces.7.html)
 - [CLONE_NEWUSER flag](https://man7.org/linux/man-pages/man2/clone.2.html)
 
-Note: clone(2) offers us the ability to enter into user and pid namespace by creatng only one process. However, clone(2) can only create new pid namespace, but cannot enter into existing pid namespaces. Therefore, to enter into existing pid namespaces, we would need to fork twice. Currently, there is no getting around this limitation.
+> Note: clone(2) offers us the ability to enter into user and pid namespace by creating only one process. However, clone(2) can only create new pid namespace, but cannot enter into existing pid namespaces. Therefore, to enter into existing pid namespaces, we would need to fork twice. Currently, there is no getting around this limitation.
 
 - [fork(2) man page](https://man7.org/linux/man-pages/man2/fork.2.html)
 - [clone(2) man page](https://man7.org/linux/man-pages/man2/clone.2.html)

docs/src/developer/liboci_cli.md

@@ -2,6 +2,6 @@
 
 This crate was separated from original youki crate, and now contains a standalone implementation of structs needed for parsing commandline arguments for OCI-spec compliant runtime commandline interface. This is in turn used by youki to parse the command line arguments passed to it, but can be used in any other projects where there is need to parse OCI spec based commandline arguments.
 
-This primarily uses the crate clap-v3 for parsing the actual commandline arguments given to the runtime.
+This primarily uses the [crate clap-v3](https://docs.rs/clap/latest/clap/index.html) for parsing the actual commandline arguments given to the runtime.
 
 You can refer to [OCI Commandline interface guide](https://github.com/opencontainers/runtime-tools/blob/master/docs/command-line-interface.md) to know more about the exact specification.

docs/src/developer/youki.md

@@ -1,6 +1,6 @@
 # youki
 
-This is the core crate that contains the youki binary itself. This provides the user interface, as well as binds the other crates together to actually perform the work of creation and management of containers. THus this provides implementation of all the commands supported by youki.
+This is the core crate that contains the youki binary itself. This provides the user interface, as well as binds the other crates together to actually perform the work of creation and management of containers. Thus, this provides implementation of all the commands supported by youki.
 
 The simple control flow of youki can be explained as :
 
@@ -10,7 +10,7 @@ The simple control flow of youki can be explained as :
 
 When given the create command, Youki will load the specification, configuration, sockets etc., and use clone syscall to create an intermediate process. This process will set the cgroups and capabilities, and then fork to the init process. Reason to create this intermediate prcoess is that the clone syscall cannot enter into existing pid namespace that has been created for the container. Thus first we need to make a transition to that namespace in the intermediate process and fork that to the container process. After that the main youki process is requested the uid and gid mappings, and after receiving them the intermediate process sets these mapping, fork the init process and return pid of this init process to the main youki process before exiting.
 
-THe init process then transition completely into the new namespace setup for the container (the init process only transitions the pid namespace). It changes the root mountpoint for the process using [pivot_root](https://man7.org/linux/man-pages/man2/pivot_root.2.html), so that the container process can get impression that it has a complete root path access. After that the init process sets up the capabilities and seccomp, and sends the seccomp notify fd to the main youki process. When the seccomp agent running on the host system sets up the seccomp profile, it notifies the init process, after which it can execute the programto be executed inside the container. Thus the init process then sends ready notification to the main youki process, and waits for the start signal.
+The init process then transition completely into the new namespace setup for the container (the init process only transitions the pid namespace). It changes the root mountpoint for the process using [pivot_root](https://man7.org/linux/man-pages/man2/pivot_root.2.html), so that the container process can get impression that it has a complete root path access. After that the init process sets up the capabilities and seccomp, and sends the seccomp notify fd to the main youki process. When the seccomp agent running on the host system sets up the seccomp profile, it notifies the init process, after which it can execute the programto be executed inside the container. Thus the init process then sends ready notification to the main youki process, and waits for the start signal.
 
 The main youki process which started creating the container, when receives the ready signals update the pid file of the container process and exits. This concludes the creation of the container.
 

docs/src/user/basic_setup.md

@@ -92,7 +92,7 @@ use liboci_cli::{...}
 
 As explained before, Youki only support Linux, and to build/use it on non-Linux Platforms, you will need to use some kind of virtualization. The repo provides a Vagrantfile to do the required VM setup using Vagrant, which can be installed from [here](https://www.vagrantup.com/docs/installation).
 
-Once installed ans setup, you can run vagrant commands in the cloned directory to run Youki inside the VM created by vagrant :
+Once installed and setup, you can run vagrant commands in the cloned directory to run Youki inside the VM created by vagrant :
 
 ```console
 # in the youki directory