Repository: pyjanitor-devs/pyjanitor

Issue:
[DOC] API Documentation for Biology functions is not standardized
# Brief Description of Fix

<!-- Please describe the fix in terms of a "before" and "after". In other words, what's not so good about the current docs
page, and what you would like to see it become. 

Example starter wording is provided. -->

Currently, the docs do not have a standard docstring format for functions.
### Example of inconsistent docstring
> (no `Returns`, no `Functional usage example`, no `Method chaining example`)
<img width="690" alt="incorrect_func_doc" src="https://user-images.githubusercontent.com/24984410/61177779-6936e100-a5a2-11e9-8332-0c02bad7b5bf.png">

### Example of a correct/desired docstring
<img width="716" alt="correct_func_doc" src="https://user-images.githubusercontent.com/24984410/61177795-c5016a00-a5a2-11e9-8cd9-415f440d95c2.png">

I would like to propose a change, such that now the docs contain a **standardized** docstring suite. All functions should contain (at a minimum) the following:
  - `Parameters`
  - ` Returns`
  - `Functional usage example`
  - `Method chaining example`

**NOTE**: This can be done for all functions within the `janitor` directory. For ease of review, this will focus on the `biology.py` file and move to other files/functions as time permits.

# Relevant Context

<!-- Please put here, in bullet points, links to the relevant docs page. A few starting template points are available
to get you started. -->

- [Link to documentation page](https://pyjanitor.readthedocs.io/reference/biology.html)
- [Link to exact file to be edited](https://github.com/loganthomas/pyjanitor/blob/dev/janitor/biology.py)

[DOC] API Documentation for Biology functions is not standardized
# Brief Description of Fix

<!-- Please describe the fix in terms of a "before" and "after". In other words, what's not so good about the current docs
page, and what you would like to see it become. 

Example starter wording is provided. -->

Currently, the docs do not have a standard docstring format for functions.
### Example of inconsistent docstring
> (no `Returns`, no `Functional usage example`, no `Method chaining example`)
<img width="690" alt="incorrect_func_doc" src="https://user-images.githubusercontent.com/24984410/61177779-6936e100-a5a2-11e9-8332-0c02bad7b5bf.png">

### Example of a correct/desired docstring
<img width="716" alt="correct_func_doc" src="https://user-images.githubusercontent.com/24984410/61177795-c5016a00-a5a2-11e9-8cd9-415f440d95c2.png">

I would like to propose a change, such that now the docs contain a **standardized** docstring suite. All functions should contain (at a minimum) the following:
  - `Parameters`
  - ` Returns`
  - `Functional usage example`
  - `Method chaining example`

**NOTE**: This can be done for all functions within the `janitor` directory. For ease of review, this will focus on the `biology.py` file and move to other files/functions as time permits.

# Relevant Context

<!-- Please put here, in bullet points, links to the relevant docs page. A few starting template points are available
to get you started. -->

- [Link to documentation page](https://pyjanitor.readthedocs.io/reference/biology.html)
- [Link to exact file to be edited](https://github.com/loganthomas/pyjanitor/blob/dev/janitor/biology.py)



Discussion:
I would like to work on this issue :)
I would like to work on this issue :)

Resolving patch:
diff --git a/janitor/biology.py b/janitor/biology.py
--- a/janitor/biology.py
+++ b/janitor/biology.py
@@ -18,7 +18,7 @@
 @pf.register_dataframe_method
 @deprecated_alias(col_name="column_name")
 def join_fasta(
-    df: pd.DataFrame, filename: str, id_col: str, column_name
+    df: pd.DataFrame, filename: str, id_col: str, column_name: str
 ) -> pd.DataFrame:
     """
     Convenience method to join in a FASTA file as a column.
@@ -36,10 +36,37 @@ def join_fasta(
 
     For more advanced functions, please use phylopandas.
 
+    Functional usage example:
+
+    .. code-block:: python
+
+        import janitor.biology
+
+        df = janitor.biology.join_fasta(
+            df=df,
+            filename='fasta_file.fasta',
+            id_col='sequence_accession',
+            column_name='sequence',
+        )
+
+    Method chaining example:
+
+    .. code-block:: python
+
+        import pandas as pd
+        import janitor.biology
+
+        df = pd.DataFrame(...).join_fasta(
+            filename='fasta_file.fasta',
+            id_col='sequence_accession',
+            column_name='sequence',
+        )
+
     :param df: A pandas DataFrame.
     :param filename: Path to the FASTA file.
     :param id_col: The column in the DataFrame that houses sequence IDs.
     :param column_name: The name of the new column.
+    :returns: A pandas DataFrame with new FASTA string sequence column.
     """
     seqrecords = {
         x.id: x.seq.__str__() for x in SeqIO.parse(filename, "fasta")


Test patch: