docs: sync rustdoc with README.md

Author: bavshin-f5

README.md

@@ -26,12 +26,12 @@ NGINX modules can be built against a particular version of NGINX. The following
 
 For example, this is how you would compile the [examples](examples) using a specific version of NGINX and enabling
 debugging:
-```
+```sh
 NGX_DEBUG=true NGX_VERSION=1.23.0 cargo build --package=examples --examples --release
 ```
 
 To build Linux-only modules, use the "linux" feature:
-```
+```sh
 cargo build --package=examples --examples --features=linux --release
 ```
 
@@ -51,13 +51,13 @@ The following environment variables can be used to change locations of cache dir
 
 In order to use the optional GNU make build process on MacOS, you will need to install additional tools. This can be
 done via [homebrew](https://brew.sh/) with the following command:
-```
+```sh
 brew install make openssl grep
 ```
 
 Additionally, you may need to set up LLVM and clang. Typically, this is done as follows:
 
-```
+```sh
 # make sure xcode tools are installed
 xcode-select --install
 # instal llvm
@@ -82,9 +82,8 @@ To do that, you need to set the `NGINX_BUILD_DIR` variable to an _absolute_ path
 Only the `./configure` step of the NGINX build is mandatory because bindings don't depend on any of the artifacts generated by `make`.
 
 
-```
+```sh
 NGINX_BUILD_DIR=$PWD/../nginx/objs cargo build --package=examples --examples
-
 ```
 
 Furthermore, this approach can be leveraged to build a module as a part of the NGINX build process by adding the `--add-module`/`--add-dynamic-module` options to the configure script.

src/lib.rs

@@ -1,4 +1,5 @@
 //! Bindings to NGINX
+//!
 //! This project provides Rust SDK interfaces to the [NGINX](https://nginx.com) proxy allowing the creation of NGINX
 //! dynamic modules completely in Rust.
 //!
@@ -14,23 +15,75 @@
 //! * `NGX_DEBUG` (default to false) -  if set to true, then will compile NGINX `--with-debug` option
 //!
 //! For example, this is how you would compile the [examples](https://github.com/nginx/ngx-rust/tree/master/examples) using a specific version of NGINX and enabling
-//! debugging: `NGX_DEBUG=true NGX_VERSION=1.23.0 cargo build --package=examples --examples --release`
+//! debugging:
+//! ```sh
+//! NGX_DEBUG=true NGX_VERSION=1.23.0 cargo build --package=examples --examples --release
+//! ```
 //!
-//! To build Linux-only modules, use the "linux" feature: `cargo build --package=examples --examples --features=linux --release`
+//! To build Linux-only modules, use the "linux" feature:
+//! ```sh
+//! cargo build --package=examples --examples --features=linux --release
+//! ```
 //!
 //! After compilation, the modules can be found in the path `target/release/examples/` ( with the `.so` file extension for
 //! Linux or `.dylib` for MacOS).
 //!
-//! Additionally, the folder  `.cache/nginx/{NGX_VERSION}/{OS}/` will contain the compiled version of NGINX used to build
-//! the SDK. You can start NGINX directly from this directory if you want to test the module or add it to `$PATH`
+//! Additionally, the folder  `.cache/nginx/{NGX_VERSION}/{TARGET}` (`{TARGET}` means rustc's target triple string)
+//! will contain the compiled version of NGINX used to build the SDK.
+//! You can start NGINX directly from this directory if you want to test the module or add it to `$PATH`
 //! ```not_rust
 //! $ export NGX_VERSION=1.23.3
 //! $ cargo build --package=examples --examples --features=linux --release
-//! $ export PATH=$PATH:`pwd`/.cache/nginx/$NGX_VERSION/macos-x86_64/sbin
+//! $ export PATH=$PATH:$PWD/.cache/nginx/$NGX_VERSION/x86_64-unknown-linux-gnu/sbin
 //! $ nginx -V
 //! $ ls -la ./target/release/examples/
 //! # now you can use dynamic modules with the NGINX
 //! ```
+//!
+//! The following environment variables can be used to change locations of cache directory and NGINX directory:
+//!
+//! * `CACHE_DIR` (default `[nginx-sys's root directory]/.cache`) - the directory containing cache files, means PGP keys, tarballs, PGP signatures, and unpacked source codes. It also contains compiled NGINX in default configuration.
+//! * `NGINX_INSTALL_ROOT_DIR` (default `{CACHE_DIR}/nginx`) - the directory containing the series of compiled NGINX in its subdirectories
+//! * `NGINX_INSTALL_DIR` (default `{NGINX_INSTALL_BASE_DIR}/{NGX_VERSION}/{TARGET}`) - the directory containing the NGINX compiled in the build
+//!
+//! ### Mac OS dependencies
+//!
+//! In order to use the optional GNU make build process on MacOS, you will need to install additional tools. This can be
+//! done via [homebrew](https://brew.sh/) with the following command:
+//! ```sh
+//! brew install make openssl grep
+//! ```
+//!
+//! Additionally, you may need to set up LLVM and clang. Typically, this is done as follows:
+//!
+//! ```sh
+//! # make sure xcode tools are installed
+//! xcode-select --install
+//! # instal llvm
+//! brew install --with-toolchain llvm
+//! ```
+//!
+//! ### Linux dependencies
+//!
+//! See the [Dockerfile] for dependencies as an example of required packages on Debian Linux.
+//!
+//! [Dockerfile]: https://github.com/nginxinc/ngx-rust/blob/master/Dockerfile
+//!
+//! ### Build with external NGINX source tree
+//!
+//! If you require a customized NGINX configuration, you can build a module against an existing pre-configured source tree.
+//! To do that, you need to set the `NGX_OBJS` variable to an _absolute_ path of the NGINX build directory (`--builddir`, defaults to the `objs` in the source directory).
+//! Only the `./configure` step of the NGINX build is mandatory because bindings don't depend on any of the artifacts generated by `make`.
+//!
+//! ```sh
+//! NGINX_BUILD_DIR=$PWD/../nginx/objs cargo build --package=examples --examples
+//! ```
+//!
+//! Furthermore, this approach can be leveraged to build a module as a part of the NGINX build process by adding the `--add-module`/`--add-dynamic-module` options to the configure script.
+//! See the following example integration scripts: [`examples/config`] and [`examples/config.make`].
+//!
+//! [`examples/config`]: https://github.com/nginxinc/ngx-rust/blob/master/examples/config
+//! [`examples/config.make`]: https://github.com/nginxinc/ngx-rust/blob/master/examples/config.make
 
 #![warn(missing_docs)]
 // support both std and no_std