Started writing documentation

git-svn-id: https://svn.kapsi.fi/jpa/nanopb@953 e3a754e5-d11d-0410-8d38-ebb782a927b9

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644 (file)
index 0000000..e4cac27
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,4 @@
+all: index.html
+
+%.html: %.rst
+       rst2html --stylesheet=lsr.css --link-stylesheet $< $@
\ No newline at end of file

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644 (file)
index 0000000..93b06e8
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,92 @@
+=============================================
+Nanopb: Protocol Buffers with small code size
+=============================================
+
+Nanopb is an ANSI-C library for encoding and decoding messages in Google's `Protocol Buffers`__ format with minimal requirements for RAM and code space.
+It is primarily suitable for 32-bit microcontrollers.
+
+__ http://code.google.com/apis/protocolbuffers/
+
+Overall structure
+=================
+
+For the runtime program, you always need *pb.h* for type declarations.
+Depending on whether you want to encode, decode or both, you also need *pb_encode.h/c* or *pb_decode.h/c*.
+
+The high-level encoding and decoding functions take an array of *pb_field_t* structures, which describes the fields of a message structure. Usually you want these autogenerated from a *.proto* file. The tool string *nanopb_generator.py* accomplishes this.
+
+So a typical project might include these files:
+
+1) Nanopb runtime library:
+    - pb.h
+    - pb_decode.h and pb_decode.c
+    - pb_encode.h and pb_encode.c
+2) Protocol description (you can have many):
+    - person.proto
+    - person.c (autogenerated, contains initializers for const arrays)
+    - person.h (autogenerated, contains type declarations)
+
+Features and limitations
+========================
+
+**Features**
+
+#) Pure C runtime
+#) Small code size (2–10 kB depending on processor)
+#) Small ram usage (typically 200 bytes)
+#) Allows specifying maximum size for strings and arrays, so that they can be allocated statically.
+#) No malloc needed: everything is stored on the stack.
+#) You can use either encoder or decoder alone to cut the code size in half.
+
+**Limitations**
+
+#) User must provide callbacks when decoding arrays or strings without maximum size.
+#) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits.
+#) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
+#) The deprecated Protocol Buffers feature called "groups" is not supported.
+
+Getting started
+===============
+
+For starters, consider this simple message::
+
+ message Example {
+    required int32 value = 1;
+ }
+
+Save this in *example.proto* and run it through *nanopb_generate.py*. You
+should now have in *example.h*::
+
+ typedef struct {
+    int32_t value;
+ } Example;
+ 
+ extern const pb_field_t Example_fields[2];
+
+Now in your main program do this to encode a message::
+
+ Example mymessage = {42};
+ uint8_t buffer[10];
+ pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
+ pb_encode(&stream, Example_fields, &mymessage);
+
+After that, buffer will contain the encoded message.
+The number of bytes in the message is stored in *stream.bytes_written*.
+You can feed the message to *protoc --decode=Example example.proto* to verify its validity.
+
+Library reference
+=================
+
+**Encoding**
+
+**Decoding**
+
+**Specifying field options**
+
+**Generated code**
+
+Wishlist
+========
+#) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
+#) A cleaner rewrite of the source generator.
+#) Better performance for 16- and 8-bit platforms.

diff --git a/docs/lsr.css b/docs/lsr.css
new file mode 100644 (file)
index 0000000..758b231
--- /dev/null
+++ b/docs/lsr.css
@@ -0,0 +1,231 @@
+/*
+Author: Peter Parente
+Date: 2008/01/22
+Version: 1.0 (modified)
+Copyright: This stylesheet has been placed in the public domain - free to edit and use for all uses.
+*/
+
+body {
+  font: 100% sans-serif;
+  background: #ffffff;
+  color: black;
+  margin: 2em;
+  padding: 0em 2em;
+}
+
+p.topic-title {
+  font-weight: bold;
+}
+
+table.docinfo {
+  text-align: left;
+  margin: 2em 0em;
+}
+
+a[href] {
+  color: #436976;
+  background-color: transparent;
+}
+
+a.toc-backref {
+  text-decoration: none;
+}
+
+h1 a[href] {
+  color: #003a6b;
+  text-decoration: none;
+  background-color: transparent;
+}
+
+a.strong {
+  font-weight: bold;
+}
+
+img {
+  margin: 0;
+  border: 0;
+}
+
+p {
+  margin: 0.5em 0 1em 0;
+  line-height: 1.5em;
+}
+
+p a:visited {
+  color: purple;
+  background-color: transparent;
+}
+
+p a:active {
+  color: red;
+  background-color: transparent;
+}
+
+a:hover {
+  text-decoration: none;
+}
+
+p img {
+  border: 0;
+  margin: 0;
+}
+
+p.rubric {
+  font-weight: bold;
+  font-style: italic;
+}
+
+em {
+  font-style: normal;
+  font-family: monospace;
+  font-weight: bold;
+}
+
+pre {
+  border-left: 3px double #aaa;
+  padding-left: 10px;
+}
+
+h1.title {
+  color: #003a6b;
+  font-size: 250%;
+  margin-bottom: 0em;
+}
+
+h2.subtitle {
+  color: #003a6b;
+  border-bottom: 0px;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  color: #555;
+  background-color: transparent;
+  margin: 0em;
+  padding-top: 0.5em;
+}
+
+h1 {
+  font-size: 160%;
+  margin-bottom: 0.5em;
+  border-bottom: 2px solid #aaa;
+}
+
+h2 {
+  font-size: 140%;
+  margin-bottom: 0.5em;
+  border-bottom: 1px solid #aaa;
+}
+
+h3 {
+  font-size: 130%;
+  margin-bottom: 0.5em;
+}
+
+h4 {
+  font-size: 110%;
+  font-weight: bold;
+  margin-bottom: 0.5em;
+}
+
+h5 {
+  font-size: 105%;
+  font-weight: bold;
+  margin-bottom: 0.5em;
+}
+
+h6 {
+  font-size: 100%;
+  font-weight: bold;
+  margin-bottom: 0.5em;
+}
+
+dt {
+  font-style: italic;
+}
+
+dd {
+  margin-bottom: 1.5em;
+}
+
+div.admonition, div.note, div.tip, div.caution, div.important {
+  margin: 2em 2em;
+  padding: 0em 1em;
+  border-top: 1px solid #aaa;
+  border-left: 1px solid #aaa;
+  border-bottom: 2px solid #555;
+  border-right: 2px solid #555;
+}
+
+div.important {
+  background: transparent url('../images/important.png') 10px 2px no-repeat;
+}
+
+div.caution {
+  background: transparent url('../images/caution.png') 10px 2px no-repeat;
+}
+
+div.note {
+  background: transparent url('../images/note.png') 10px 2px no-repeat;
+}
+
+div.tip {
+  background: transparent url('../images/tip.png') 10px 2px no-repeat;
+}
+
+div.admonition-example {
+  background: transparent url('../images/tip.png') 10px 2px no-repeat;
+}
+
+div.admonition-critical-example {
+  background: transparent url('../images/important.png') 10px 2px no-repeat;
+}
+
+p.admonition-title {
+  font-weight: bold;
+  border-bottom: 1px solid #aaa;
+  padding-left: 30px;
+}
+
+table.docutils {
+  text-align: left;
+  border: 1px solid gray;
+  border-collapse: collapse;
+  width: 100%;
+  margin: 1.5em 0em;
+}
+
+table.docutils caption {
+  font-style: italic;
+}
+
+table.docutils td, table.docutils th {
+  padding: 0.25em 0.5em;
+}
+
+table.docutils th {
+  background-color: #dddddd;
+}
+
+div.sidebar {
+  width: 33%;
+  float: right;
+  margin: 0em 2em;
+  padding: 0em 1em;
+  border-top: 1px solid #aaa;
+  border-left: 1px solid #aaa;
+  border-bottom: 2px solid #555;
+  border-right: 2px solid #555;
+}
+
+p.sidebar-title {
+  margin-bottom: 0em;
+  color: #003a6b;
+  border-bottom: 1px solid #aaa;
+  font-weight: bold;
+}
+
+p.sidebar-subtitle {
+  margin-top: 0em;
+  font-style: italic;
+  color: #003a6b;
+}

diff --git a/pb.h b/pb.h
index 46d7c2c..1d32ee9 100644 (file)
--- a/pb.h
+++ b/pb.h
@@ -12,7 +12,7 @@
 #define pb_packed
 #endif
 
-/* Wire types */
+/* Wire types. Library user needs these only in encoder callbacks. */
 typedef enum {
     PB_WT_VARINT = 0,
     PB_WT_64BIT  = 1,