Reorganize the documentation

Author: jonas

CONTRIBUTING.md

@@ -30,6 +30,12 @@ cd tests
 sbt ~test
 ```
 
+To run the same tests as is run by Travis CI use the `test.sh` script, which will both build the executable and run `sbt verify`:
+
+```sh
+./scripts/test.sh
+```
+
 ## Coding Guidelines
 
 Code should be formatted with `./scripts/scalafmt` and `./scripts/clangfmt`.

build.sbt

@@ -168,14 +168,17 @@ lazy val docs = project("docs")
   .enablePlugins(GhpagesPlugin, ParadoxSitePlugin, ParadoxMaterialThemePlugin)
   .settings(
     publish / skip := true,
+    scalaVersion := Versions.scala211,
     Paradox / paradoxProperties ++= Map(
       "github.base_url" -> scmInfo.value.get.browseUrl.toString
     ),
     ParadoxMaterialThemePlugin.paradoxMaterialThemeSettings(Paradox),
     Paradox / paradoxMaterialTheme := {
+      val licenseUrl = scmInfo.value.get.browseUrl.toString + "blob/master/LICENSE.txt"
       (Paradox / paradoxMaterialTheme).value
         .withRepository(scmInfo.value.get.browseUrl.toURI)
         .withColor("indigo", "indigo")
+        .withCopyright(s"Copyright © Liudmila Kornilova, distributed under the <a href='$licenseUrl'>Scala license</a>.")
     }
   )
 

docs/src/paradox/cli.md

@@ -0,0 +1,55 @@
+# Generating Bindings with the CLI
+
+Statically linked executables are provided with each release for Linux and macOS. Head over to the [releases page] to download the latest version for your platform.
+
+ [releases page]: https://github.com/kornilova-l/scala-native-bindgen/releases
+
+@@@ note
+
+In the following we assume you have renamed the downloaded `scala-native-bindgen-$PLATFORM` file to `scala-native-bindgen`.
+
+@@@
+
+## Command Line Usage
+
+When generating bindings with the CLI, you need to specify the header file and provide the name of the created bindings using the `--name` option:
+
+```sh
+scala-native-bindgen --name fnmatch /usr/include/fnmatch.h --
+```
+
+When running the CLI it will also yield warnings along with the translation. To keep only the bindings please redirect the output to a file like this:
+
+```sh
+scala-native-bindgen --name fnmatch /usr/include/fnmatch.h -- > fnmatch.scala
+```
+
+By default it is assumed that you want to link with a library based on the name option.
+In case the name of the library to link with is different from the binding name provide the library name using `--link`:
+
+```sh
+scala-native-bindgen --name zlib --link z /usr/include/zlib.h --
+```
+
+If the binding does not require any linking, pass `--no-link`:
+
+```sh
+scala-native-bindgen --name fnmatch --no-link /usr/include/fnmatch.h --
+```
+
+For libraries that require linking you m
+
+## Options
+
+The generated bindings can be configured using the different options and it is also possible to pass arguments directly to the Clang compiler using the `--extra-arg*` options.
+
+| Option               | Description
+|----------------------|---------------------------------------------------------------------------------|
+| `--link`             | Library to link with, e.g. `--link` uv for libuv.
+| `--no-link`          | Library does not require linking.
+| `--name`             | Scala object name that contains bindings. Default value set to library name.
+| `--package`          | Package name of generated Scala file.
+| `--exclude-prefix`   | Functions and unused typedefs will be removed if their names have given prefix.
+| `--binding-config`   | Path to a config file that contains the information about bindings that should be reused. See @ref:[Integrating Bindings](integrating-bindings.md) for more information.
+| `--extra-arg`        | Additional argument to append to the compiler command line.
+| `--extra-arg-before` | Additional argument to prepend to the compiler command line.

docs/src/paradox/command-line-usage/index.md

@@ -1,4 +1,4 @@
-# Building with `CMake`
+# Building the executable with `CMake`
 
 Building `scala-native-bindgen` requires the following tools and libraries:
 
@@ -40,16 +40,6 @@ equivalent, e.g. to compile with debug symbols the following are the same:
 ```sh
 cmake -DCMAKE_CXX_FLAGS=-g ..
 CXXFLAGS=-g cmake ..
-```
-
-## Testing
-
-The tests assume that the above instructions for building `scala-native-bindgen` from source
-has been followed.
-
-```sh
-cd tests
-sbt test
 ```
 
  [CMake]: https://cmake.org/

docs/src/paradox/obtaining-bindgen/cmake.md renamed to docs/src/paradox/contrib/cmake.md

@@ -1,4 +1,4 @@
-# Building with `docker-compose`
+# Building the executable with `docker-compose`
 
 You can use [docker-compose] to build and test the program:
 
@@ -11,4 +11,5 @@ docker-compose run --rm ubuntu-18.04-llvm-6.0 ./script/test.sh
 docker-compose run --rm ubuntu-18.04-llvm-6.0 \
     bindgen/target/scala-native-bindgen --name union tests/samples/Union.h --
 ```
+
  [docker-compose]: https://docs.docker.com/compose/

docs/src/paradox/obtaining-bindgen/docker-compose.md renamed to docs/src/paradox/contrib/docker-compose.md

@@ -0,0 +1 @@
+../../../../CONTRIBUTING.md

docs/src/paradox/contrib/guidelines.md

@@ -0,0 +1,15 @@
+# Contributor's Guide
+
+Contributions to the project is very welcome. This section provides more
+information about how to build and contribute to the project.
+
+@@ toc
+
+@@@ index
+
+* [guidelines](guidelines.md)
+* [cmake](cmake.md)
+* [docker-compose](docker-compose.md)
+* [releasing](releasing.md)
+
+@@@

docs/src/paradox/contrib/index.md

@@ -0,0 +1,21 @@
+# Release Workflow
+
+First build the `scala-native-bindgen` executable for both macOS and
+Linux:
+
+```sh
+scripts/prepare-release.sh
+```
+
+You should now have `scala-native-bindgen-linux` and
+`scala-native-bindgen-darwin` if you ran the script on a macOS machine.
+
+Then release version `x.y.z` by running:
+
+```sh
+sbt -Dproject.version=x.y.z release
+```
+
+Finally, upload the `scala-native-bindgen-linux` and
+`scala-native-bindgen-darwin` executables to the release page at:
+<https://github.com/kornilova-l/scala-native-bindgen/releases/tag/vx.y.z>

docs/src/paradox/contrib/releasing.md

@@ -1,21 +1,37 @@
 # Scala Native Bindgen
 
-@@@ index
-
-* [Obtaining Bindgen](obtaining-bindgen/index.md)
-* [Command Line Usage](command-line-usage/index.md)
-* [Integrating Bindings](integrating-bindings/index.md)
-* [Limitations](limitations/index.md)
-* [Using Generated Bindings](using-generated-bindings/README.md)
+Scala Native Bindgen is a binding generator for Scala Native that uses [Clang] to
+parse C header files and generates Scala binding definitions.
 
-@@@
+## Features
 
-This tool generates Scala Native bindings from C headers.
-It's built upon clang and [LibTooling] and thus respects the conventions of clang-tools.
+* possibility to reuse types from existing bindings.
+* type casts that make recursive structs be valid Scala Native structs.
+* implicit classes for structs and unions that make fields access easier.
+* implicit classes that add setters and getters to structs with more than 22 fields (such structs in Scala
+  Native are represented as arrays of bytes).
+* literal defines embedding `#define MY_CONSTANT 42` → `val MY_CONSTANT: native.CInt = 42`.
+* read-only bindings for extern variables (such variables cannot be updated due to Scala Native limitation).
+* declarations filtering by prefix.
 
 ## License
 
 This project is distributed under the Scala license.
 @github[See LICENSE.txt for details](/LICENSE.txt)
 
- [LibTooling]: https://clang.llvm.org/docs/LibTooling.html
+ [Clang]: https://clang.llvm.org/
+
+## Table of Contents
+
+@@ toc
+
+@@@ index
+
+* [sbt](sbt.md)
+* [cli](cli.md)
+* [Using Generated Bindings](using-generated-bindings.md)
+* [Integrating Bindings](integrating-bindings.md)
+* [Limitations](limitations.md)
+* [Contributor's Guide](contrib/index.md)
+
+@@@

docs/src/paradox/index.md

@@ -1,6 +1,7 @@
 # Integrating Bindings
 
 To reuse already generated bindings create a `config.json` file that defines which headers correspond to which Scala objects:
+
 ```json
 {
   "_stdio.h": "scala.scalanative.native.stdio",
@@ -10,6 +11,7 @@ To reuse already generated bindings create a `config.json` file that defines whi
 
 Bindgen assumes that type names in header files match type names in generated binding (spaces in struct, union and enum
 names are replaces with underscores), but it is possible to specify custom names mapping:
+
 ```json
 {
   "hiredis.h": {
@@ -22,4 +24,4 @@ names are replaces with underscores), but it is possible to specify custom names
 ```
 
 Provide a path to `config.json` to bindgen using `--binding-config` command-line option or `NativeBinding.bindingConfig`
-sbt plugin option (see @ref:[Using the sbt plugin](../obtaining-bindgen/sbt-plugin.md)).
+sbt plugin option (see @ref:[Using the sbt plugin](sbt.md)).

docs/src/paradox/integrating-bindings/index.md renamed to docs/src/paradox/integrating-bindings.md

@@ -2,6 +2,8 @@
 
 There are multiple unsupported cases that should be considered when generating bindings.
 
+@@ toc
+
 ## Passing structs by value
 
 Scala Native does not support passing structs by value, bindgen skips such functions.

docs/src/paradox/limitations/index.md renamed to docs/src/paradox/limitations.md

@@ -1,4 +1,4 @@
-# Using the sbt plugin
+# Generating Bindings with sbt
 
 To add the sbt plugin to your project add the following lines in `project/plugins.sbt`:
 
@@ -27,31 +27,12 @@ nativeBindgenPath := file("/path/to/scala-native-bindgen")
 
 Example settings:
 
-```sbt
-enablePlugins(ScalaNativeBindgenPlugin)
-inConfig(Compile)(
-  Def.settings(
-    nativeBindings += {
-      NativeBinding((resourceDirectory in Compile).value / "header.h")
-        .name("MyLib")
-        .packageName("org.example.mylib")
-        .link("mylib"), // Will pass `-lmylib` to the linker
-        .excludePrefix("__")
-      }
-  ))
-```
+@@snip [sbt] (../../../sbt-scala-native-bindgen/src/sbt-test/bindgen/generate/build.sbt) { #example }
 
-Running `nativeBindgen` will generate a file named `target/scala-2.x/src_managed/main/sbt-scala-native-bindgen/MyLib.scala` containing something along the following lines:
+Given that the `stdlib.h` header file contains:
 
-```scala
-package org.example.mylib
+@@snip [sbt] (../../../sbt-scala-native-bindgen/src/sbt-test/bindgen/generate/src/main/resources/stdlib.h)
 
-import scala.scalanative._
-import scala.scalanative.native._
+Running `nativeBindgen` will generate a file named `target/scala-2.11/src_managed/main/sbt-scala-native-bindgen/stdlib.scala` containing something along the following lines:
 
-@native.link("mylib")
-@native.extern
-object MyLib {
-  // ... left out for brevity ...
-}
-```
+@@snip [sbt] (../../../sbt-scala-native-bindgen/src/sbt-test/bindgen/generate/expected/stdlib.scala)