Add Packer.buffer() (#320)

3 files changed, 34 insertions, 1 deletions

diff --git a/docs/Makefile b/docs/Makefile
index b09d884..831a6a7 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -153,7 +153,7 @@ doctest:
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 serve: html
-	cd _build/html && python3 -m http.server
+	python3 -m http.server -d _build/html
 
 zip: html
 	cd _build/html && zip -r ../../../msgpack-doc.zip .
diff --git a/docs/advanced.rst b/docs/advanced.rst
new file mode 100644
index 0000000..3837008
--- /dev/null
+++ b/docs/advanced.rst
@@ -0,0 +1,32 @@
+Advanced usage
+===============
+
+Packer
+------
+
+autoreset
+~~~~~~~~~
+
+When you used ``autoreset=False`` option of :class:`~msgpack.Packer`, 
+``pack()`` method doesn't return packed ``bytes``.
+
+You can use :meth:`~msgpack.Packer.bytes` or :meth:`~msgpack.Packer.getbuffer` to
+get packed data.
+
+``bytes()`` returns ``bytes`` object.  ``getbuffer()`` returns some bytes-like
+object.  It's concrete type is implement detail and it will be changed in future
+versions.
+
+You can reduce temporary bytes object by using ``Unpacker.getbuffer()``.
+
+.. code-block:: python
+
+    packer = Packer(use_bin_type=True, autoreset=False)
+
+    packer.pack([1, 2])
+    packer.pack([3, 4])
+
+    with open('data.bin', 'wb') as f:
+        f.write(packer.getbuffer())
+
+    packer.reset()  # reset internal buffer
diff --git a/docs/index.rst b/docs/index.rst
index dcdab4f..e9c2ce8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,3 +8,4 @@ language data exchange.
    :maxdepth: 1
 
    api
+   advanced