From 8340516801e70d24e0102f51f6124c90fa247560 Mon Sep 17 00:00:00 2001
From: Robert Jordens <jordens@gmail.com>
Date: Mon, 23 Mar 2015 18:16:39 -0600
Subject: [PATCH] doc/manual: add faq (edited from artiq-log)

---
 doc/manual/faq.rst   | 68 ++++++++++++++++++++++++++++++++++++++++++++
 doc/manual/index.rst |  1 +
 2 files changed, 69 insertions(+)
 create mode 100644 doc/manual/faq.rst

diff --git a/doc/manual/faq.rst b/doc/manual/faq.rst
new file mode 100644
index 000000000..825b93dd9
--- /dev/null
+++ b/doc/manual/faq.rst
@@ -0,0 +1,68 @@
+FAQ
+###
+
+How do I ...
+============
+
+override the sysclk frequency of just one dds?
+----------------------------------------------
+
+Override the parameter using an argument in the ddb.
+
+organize parameters in folders?
+-------------------------------
+
+Use gui auto-completion and filtering.
+Names need to be unique.
+
+enforce functional dependencies between parameters?
+---------------------------------------------------
+
+Use wrapper experiments, overriding parameters of arguments.
+
+get rid of `DbKeys`?
+--------------------
+
+`DbKeys` enforces valid parameter/argument names, references
+keys in pdb and hints at metadata on how values can be retrieved.
+
+write a generator feeding a kernel feeding an analyze function?
+---------------------------------------------------------------
+
+  Like this::
+
+    def run(self):
+        self.parse(self.pipe(iter(range(10))))
+
+    def pipe(self, gen):
+        for i in gen:
+            r = self.do(i)
+            yield r
+
+    def parse(self, gen):
+        for i in gen:
+            pass
+
+    @kernel
+    def do(self, i):
+        return i
+
+create and use variable lengths arrays?
+------------------------------------------------
+
+Don't. Preallocate everything. Or chunk it and e.g. read 100 events per
+function call, push them upstream and retry until the gate time closes.
+
+execute multiple slow controller RPCs in parallel without loosing time? 
+-----------------------------------------------------------------------
+
+Use `threading.Thread`: portable, fast, simple for one-shot calls
+
+write part of my experiment as a coroutine/Task/generator?
+----------------------------------------------------------
+
+You want to write experiment preparation (`__init__()` or `build()`)
+or analysis (`analyze()`)
+
+No. That would make reusing your own code in sub-experiments difficult and
+fragile.
diff --git a/doc/manual/index.rst b/doc/manual/index.rst
index b1705a42d..34baa6df9 100644
--- a/doc/manual/index.rst
+++ b/doc/manual/index.rst
@@ -16,3 +16,4 @@ Contents:
     ndsp_reference
     utilities
     fpga_board_ports
+    faq