Revamping the FlatBuffers docs.

Adding an API reference for the supported languages.

General docs cleanup, including a new `tutorial` section that
supports all of the supported languages.

Added samples for each supported language to mirror the new
tutorial page.

Cleaned up all the links by making them `@ref` style links,
instead of referencing the names of the generated `.html` files.

Removed all generated files that were unnecessarily committed.

Also fixed the C# tests (two were failing due to a missing file).

Bug: b/25801305

Tested: Tested all samples on Ubuntu, Mac, and Android. Docs were
generated using doxygen and viewed on Chrome.

Change-Id: I2acaba6e332a15ae2deff5f26a4a25da7bd2c954

docs/source/PythonUsage.md

@@ -1,11 +1,52 @@
-# Use in Python
+Use in Python    {#flatbuffers_guide_use_python}
+=============
 
-There's experimental support for reading FlatBuffers in Python. Generate
-code for Python with the `-p` option to `flatc`.
+## Before you get started
 
-See `py_test.py` for an example. You import the generated code, read a
-FlatBuffer binary file into a `bytearray`, which you pass to the
-`GetRootAsMonster` function:
+Before diving into the FlatBuffers usage in Python, it should be noted that the
+[Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to general
+FlatBuffers usage in all of the supported languages (including Python). This
+page is designed to cover the nuances of FlatBuffers usage, specific to
+Python.
+
+You should also have read the [Building](@ref flatbuffers_guide_building)
+documentation to build `flatc` and should be familiar with
+[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
+[Writing a schema](@ref flatbuffers_guide_writing_schema).
+
+## FlatBuffers Python library code location
+
+The code for the FlatBuffers Python library can be found at
+`flatbuffers/python/flatbuffers`. You can browse the library code on the
+[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/
+python).
+
+## Testing the FlatBuffers Python library
+
+The code to test the Python library can be found at `flatbuffers/tests`.
+The test code itself is located in [py_test.py](https://github.com/google/
+flatbuffers/blob/master/tests/py_test.py).
+
+To run the tests, use the [PythonTest.sh](https://github.com/google/flatbuffers/
+blob/master/tests/PythonTest.sh) shell script.
+
+*Note: This script requires [python](https://www.python.org/) to be
+installed.*
+
+## Using the FlatBuffers Python library
+
+*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
+example of how to use FlatBuffers in Python.*
+
+There is support for both reading and writing FlatBuffers in Python.
+
+To use FlatBuffers in your own code, first generate Python classes from your
+schema with the `--python` option to `flatc`. Then you can include both
+FlatBuffers and the generated code to read or write a FlatBuffer.
+
+For example, here is how you would read a FlatBuffer binary file in Python:
+First, import the library and the generated code. Then read a FlatBuffer binary
+file into a `bytearray`, which you pass to the `GetRootAsMonster` function:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.py}
     import MyGame.Example as example
@@ -23,93 +64,10 @@ Now you can access values like this:
     pos = monster.Pos()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To access vectors you pass an extra index to the
-vector field accessor. Then a second method with the same name suffixed
-by `Length` let's you know the number of elements you can access:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.py}
-    for i in xrange(monster.InventoryLength()):
-        monster.Inventory(i) # do something here
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can also construct these buffers in Python using the functions found
-in the generated code, and the FlatBufferBuilder class:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.py}
-    builder = flatbuffers.Builder(0)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Create strings:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.py}
-    s = builder.CreateString("MyMonster")
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Create a table with a struct contained therein:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.py}
-    example.MonsterStart(builder)
-    example.MonsterAddPos(builder, example.CreateVec3(builder, 1.0, 2.0, 3.0, 3.0, 4, 5, 6))
-    example.MonsterAddHp(builder, 80)
-    example.MonsterAddName(builder, str)
-    example.MonsterAddInventory(builder, inv)
-    example.MonsterAddTest_Type(builder, 1)
-    example.MonsterAddTest(builder, mon2)
-    example.MonsterAddTest4(builder, test4s)
-    mon = example.MonsterEnd(builder)
-
-    final_flatbuffer = builder.Output()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Unlike C++, Python does not support table creation functions like 'createMonster()'.
-This is to create the buffer without
-using temporary object allocation (since the `Vec3` is an inline component of
-`Monster`, it has to be created right where it is added, whereas the name and
-the inventory are not inline, and **must** be created outside of the table
-creation sequence).
-Structs do have convenient methods that allow you to construct them in one call.
-These also have arguments for nested structs, e.g. if a struct has a field `a`
-and a nested struct field `b` (which has fields `c` and `d`), then the arguments
-will be `a`, `c` and `d`.
-
-Vectors also use this start/end pattern to allow vectors of both scalar types
-and structs:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.py}
-    example.MonsterStartInventoryVector(builder, 5)
-    i = 4
-    while i >= 0:
-        builder.PrependByte(byte(i))
-        i -= 1
-
-    inv = builder.EndVector(5)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The generated method 'StartInventoryVector' is provided as a convenience
-function which calls 'StartVector' with the correct element size of the vector
-type which in this case is 'ubyte' or 1 byte per vector element.
-You pass the number of elements you want to write.
-You write the elements backwards since the buffer
-is being constructed back to front. Use the correct `Prepend` call for the type,
-or `PrependUOffsetT` for offsets. You then pass `inv` to the corresponding
-`Add` call when you construct the table containing it afterwards.
-
-There are `Prepend` functions for all the scalar types. You use
-`PrependUOffset` for any previously constructed objects (such as other tables,
-strings, vectors). For structs, you use the appropriate `create` function
-in-line, as shown above in the `Monster` example.
-
-Once you're done constructing a buffer, you call `Finish` with the root object
-offset (`mon` in the example above). Your data now resides in Builder.Bytes.
-Important to note is that the real data starts at the index indicated by Head(),
-for Offset() bytes (this is because the buffer is constructed backwards).
-If you wanted to read the buffer right after creating it (using
-`GetRootAsMonster` above), the second argument, instead of `0` would thus
-also be `Head()`.
-
 ## Text Parsing
 
 There currently is no support for parsing text (Schema's and JSON) directly
 from Python, though you could use the C++ parser through SWIG or ctypes. Please
 see the C++ documentation for more on text parsing.
 
+<br>