Add File Options documentation.

Fixes #8

_data/nav.yml

@@ -4,4 +4,6 @@
   url: /sbt-settings.html
 - text: Generated Code
   url: /generated-code.html
+- text: File Options
+  url: /file-options.html
 

_data/version.yml

@@ -1,2 +1,2 @@
-scalapb: 0.4.1
-sbt_scalapb: 0.4.1
+scalapb: 0.4.2
+sbt_scalapb: 0.4.2

file-options.md

@@ -0,0 +1,44 @@
+---
+title: "ScalaPB: File Options"
+layout: page
+---
+
+# ScalaPB File-level Options
+
+ScalaPB file-level options lets you
+
+- specify the Scala package to use, independently of the Java package option.
+- request that ScalaPB will not append the protofile name to the package name.
+
+The file-level options are not required, unless you are interested in those
+customizations. If you do not want to customize the defaults, you can safely
+skip this section.
+
+## Supported options
+
+{% highlight proto %}
+import "scalapb/scalapb.proto";
+
+option (scalapb.options) = {
+  package_name: "com.example.myprotos"
+  flat_package: true
+};
+{% endhighlight %}
+
+- `package_name` sets the Scala base package name, if this is not defined,
+then it falls back to `java_package` and then to `package`. 
+
+- `flat_package` settings makes ScalaPB not append the protofile base name
+to the package name.  You can also apply this option globally to all files
+by adding it to your [ScalaPB SBT Settings]({{site.baseurl}}/sbt-settings.html).
+
+## Adding scalapb.proto to your project
+
+The easiest way to get `protoc` to find `scalapb/scalapb.proto` when compiling
+through SBT is by adding the following to your `build.sbt`:
+
+    libraryDepenencies += "com.trueaccord.scalapb" %% "scalapb-runtime" % "{{site.data.version.scalapb}}" % PB.protobufConfig
+
+If you are invoking `protoc` manually, you will need to ensure that the files in
+[`protobuf`](https://github.com/trueaccord/ScalaPB/tree/master/protobuf)
+directory are available to your project.

generated-code.md

@@ -7,13 +7,13 @@ layout: page
 
 This page describes the code generated by ScalaPB and how to use it.
 
-## Package and outer object
+## Default Package Structure
 
 The generator will create a Scala file for each top-level message and enum
 in your proto file. Using multiple files results in a better incremental
 compilation performance.
 
-The Scala package of the generated files will be the determined as followed:
+The Scala package of the generated files will be determined as follows:
 
 - If the `java_package` option is defined, then the Scala package will be
   `java_package.base_name` where `base_name` is the name of the proto file
@@ -24,6 +24,9 @@ The Scala package of the generated files will be the determined as followed:
 - If neither `java_package` nor `package` are specified, the Scala package
   will be just `base_name`.
 
+From version 0.4.2, there is a way to customize the package name by using
+[file-level options]({{site.baseurl}}/file-options.html).
+
 ## Messages
 
 Each message corresponds to a final case class and a companion object.

sbt-settings.md

@@ -36,6 +36,13 @@ To enable Java conversions add the following to your build.sbt:
 
     PB.javaConversions in PB.protobufConfig := true
 
+## Flat Packages
+
+You can request that ScalaPB will not append the protofile base name
+by adding:
+
+    PB.flatPackage in PB.protobufConfig := true
+
 ## Pulling a newer version of the Scala code generator
 
 The sbt-scalapb plugin is configured to use a specific version of the code