Merge pull request mmistakes#84 from pesser/faq

Faq

docs/index.rst

@@ -26,6 +26,7 @@ Contents
    source/models
    source/iterator
    source/contributions
+   source/faq
    source/source_files/modules
 
 Indices and tables

docs/source/contributions.rst

@@ -18,24 +18,24 @@ black_ to your pre-commit hook:
 
 0. Install black_ with ::
 
-   $ pip install black
+    $ pip install black
 
 1. Paste the following into at the top <project-root>/.git/hooks/pre-commit.sample::
 
-   # run black on all staged files
-   staged=$(git diff --name-only --cached)
-   black $staged
-   # add them again after formatting
-   git add $staged
+    # run black on all staged files
+    staged=$(git diff --name-only --cached)
+    black $staged
+    # add them again after formatting
+    git add $staged
 
 2. Rename ``pre-commit.sample`` to ``pre-commit``
 3. Make it executable using::
 
-   $ chmod +x pre-commit
+    $ chmod +x pre-commit
 
 4. Done!
 
-Or run black by hand and use this command before every commit:::
+Or run black by hand and use this command before every commit::
 
     black ./
 
@@ -44,14 +44,14 @@ Continuous Integration
 ======================
 
 We use travisCI_ for continuous integration.
-You do not need to worry about as long as your code passes all tests (this includes
+You do not need to worry about it as long as your code passes all tests (this includes
 a formatting test with black).
 
 .. note::
 
     this should include an example to run the tests locally as well
 
-Documenation
+Documentation
 ============
 
    This is a short summary how the documentation works and how it can be built
@@ -62,21 +62,25 @@ It also uses all-contributors_ for honoring contributors.
 sphinx
 ------
 
-To build the documentation locally, install `sphinx` and run:::
+To build the documentation locally, install `sphinx` ::
+
+   pip install sphinx sphinx_rtd_theme
+
+and run ::
 
     $ cd docs
     $ make html
 
 The html files are available under the then existing directory ``docs/_build/html/``
 
-The docsting format which is preferred is `numpy`.
+The preferred docsting format is `numpy <https://numpydoc.readthedocs.io/en/latest/format.html>`__.
 
 We use `sphinx-apidoc` to track all files automatically:::
 
     $ cd docs
     $ sphinx-apidoc -o ./source/source_files ../edflow
 
-all-contirbutors
+all-contributors
 ----------------
 
 We use all-contributors locally and manage the contributors by hand.

docs/source/faq.rst

@@ -0,0 +1,19 @@
+
+FAQ
+=====
+
+How do I set a random seed?
+   Iterators or models or datasets can use a random seed from
+   the config. How and where to set such seeds is application
+   specific. It is recommended to create local pseudo-random-number-generators
+   whenever possible, e.g. using `RandomState
+   <https://docs.scipy.org/doc/numpy/reference/generated/numpy.random.RandomState.html>`_
+   for `numpy`.
+
+   Note that loading examples from a dataset happens in multiple processes, and
+   the same random seed is copied to all child processes. If your
+   :meth:`edflow.data.dataset.DatasetMixin.get_example` method relies on random
+   numbers, you should use :class:`edflow.util.PRNGMixin` to make sure examples
+   in your batches are independent. This will add a :attr:`prng` attribute (a
+   `RandomState` instance) to your class, which will be seeded differently in
+   each process.