Add examples of using BIOM

[wasade]

Add examples (in doctest?) of using BIOM objects

[wasade]

ping people in lab for examples, leave unstructured right now, push for doctest use within 1.1

[gregcaporaso]

added a quick example of table_factory in the table_factory doc string.

[jairideout]

@wasade and I discussed this and are moving it to 1.2.0 since we have limited time before the release and not many devs have been asking about how to use these classes.

[wasade]

@antgonza, do you have bandwidth to work on examples?

[wasade]

Specifically, it would be ideal to have examples of:

• Constructing tables with Table
• Table.exists
• Table.filter
• Table.norm
• Table.transform
• Table.sort
• Table.metadata
• Table.sum
• Table.reduce
• Table.iter
• Table.merge
• Table.collapse
• Table.partition
• Table.iter_data

What we need, also ideally, are examples in the method docstrings, and a coherent module level docstring for biom.table. Of the above, I think an example at the module level of the following would likely get people generally oriented:

• create a Table
• normalize the Table
• filter the Table
• summarize the Table in some interesting fashion

[ElDeveloper]

While working on #383 I realized that this issue is not going to be properly rendered if the numpydoc sphinx extension is not present.

[wasade]

@ElDeveloper, could you create an issue for including numpydoc please?

[ElDeveloper]

#277 should serve as that issue.

[wasade]

Just to make a note, I'm going to start working on the module level docstring

[ElDeveloper]

I'll take merge.

[teravest]

I'll finish out the list with collapse

[ElDeveloper]