Repository: pyjanitor-devs/pyjanitor

Issue:
List of general functions and their documentation isn't showing up in the documentation
"General Functions" link on this page doesn't open the list of general functions and their documentation:

This link: https://pyjanitor-devs.github.io/pyjanitor/api/functions/

and this link: https://pyjanitor-devs.github.io/pyjanitor/api/functions/#janitor.functions--general-functions

display same page. 

All other "API Reference" subsection links--Biology, Chemistry, Engineering, etc.--display functions & descriptions, but not the General 
 



Discussion:
I can make sure `mkdocstrings` 0.19.0 #1138 cause this.
0.19.0 is breaking changing version.

The lower version use `mkdocstrings-python-legacy` as the documentation hander.

A quickly fix this we can [`mkdocstrings-python-legacy`](https://pypi.org/project/mkdocstrings-python-legacy/) as the default handler instead of [`mkdocstrings-python`](https://pypi.org/project/mkdocstrings-python/)

As the developer said, `mkdocstrings-python` is the future.
`mkdocstrings-python-legacy` official has a note.
> WARNING: We suggest using the new handler instead: [mkdocstrings-python](https://mkdocstrings.github.io/python/).
I know little about mkdocs, I use sphinx a lot.
I don't why functions documentation missing.

But I know how to fix this.
![image](https://user-images.githubusercontent.com/25895405/184469169-48e4801f-0113-42f0-9672-6a8290c65b93.png)
```diff
    Method chaining usage example:

-    >>> import pandas as pd
-    >>> import janitor.finance
-    >>> df = pd.DataFrame({"profit":[100.10, 200.20, 300.30, 400.40, 500.50]})
-    >>> df
-       profit
-    0   100.1
-    1   200.2
-    2   300.3
-    3   400.4
-    4   500.5
-    >>> df.inflate_currency(
-    ...    column_name='profit',
-    ...    country='USA',
-    ...    currency_year=2015,
-    ...    to_year=2018,
-    ...    make_new_column=True
-    ... )
-       profit  profit_2018
-    0   100.1   106.050596
-    1   200.2   212.101191
-    2   300.3   318.151787
-    3   400.4   424.202382
-    4   500.5   530.252978
+    ```python
+    >>> import pandas as pd
+    >>> import janitor.finance
+    >>> df = pd.DataFrame({"profit":[100.10, 200.20, 300.30, 400.40, 500.50]})
+    >>> df
+       profit
+    0   100.1
+    1   200.2
+    2   300.3
+    3   400.4
+    4   500.5
+    >>> df.inflate_currency(
+    ...    column_name='profit',
+    ...    country='USA',
+    ...    currency_year=2015,
+    ...    to_year=2018,
+    ...    make_new_column=True
+    ... )
+       profit  profit_2018
+    0   100.1   106.050596
+    1   200.2   212.101191
+    2   300.3   318.151787
+    3   400.4   424.202382
+    4   500.5   530.252978
+    ```
```

or

```diff
    Method chaining usage example:

-    >>> import pandas as pd
-    >>> import janitor.finance
-    >>> df = pd.DataFrame({"profit":[100.10, 200.20, 300.30, 400.40, 500.50]})
-    >>> df
-       profit
-    0   100.1
-    1   200.2
-    2   300.3
-    3   400.4
-    4   500.5
-    >>> df.inflate_currency(
-    ...    column_name='profit',
-    ...    country='USA',
-    ...    currency_year=2015,
-    ...    to_year=2018,
-    ...    make_new_column=True
-    ... )
-       profit  profit_2018
-    0   100.1   106.050596
-    1   200.2   212.101191
-    2   300.3   318.151787
-    3   400.4   424.202382
-    4   500.5   530.252978
+       >>> import pandas as pd
+       >>> import janitor.finance
+       >>> df = pd.DataFrame({"profit":[100.10, 200.20, 300.30, 400.40, 500.50]})
+       >>> df
+          profit
+       0   100.1
+       1   200.2
+       2   300.3
+       3   400.4
+       4   500.5
+       >>> df.inflate_currency(
+       ...    column_name='profit',
+       ...    country='USA',
+       ...    currency_year=2015,
+       ...    to_year=2018,
+       ...    make_new_column=True
+       ... )
+          profit  profit_2018
+       0   100.1   106.050596
+       1   200.2   212.101191
+       2   300.3   318.151787
+       3   400.4   424.202382
+       4   500.5   530.252978
```

thanks @DavidHinchee for the observation. @Zeroto521 @ericmjl should we revert temporarily to `mkdocs-python-legacy`?
Does Mkdocs have documentation version feature?
We always let us see latest version. But some new coming features are not in stable (released) package.
If Mkdocs owns this feature, we could easily fix it via pointing site to stable version documentation.
![image](https://user-images.githubusercontent.com/25895405/184518996-9132d8c8-6de7-43f2-be72-2564ecaee8d9.png)
@Zeroto521 something like this: [link](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#versioning)
I am pushing up a temporary fix for the docs; we will pin `mkdocstrings` to 0.18.1. In a future PR, this can be fixed up.

Resolving patch:
diff --git a/janitor/biology.py b/janitor/biology.py
--- a/janitor/biology.py
+++ b/janitor/biology.py
@@ -41,32 +41,32 @@ def join_fasta(
 
     Method chaining usage example:
 
-    >>> import tempfile
-    >>> import pandas as pd
-    >>> import janitor.biology
-
-    >>> tf = tempfile.NamedTemporaryFile()
-    >>> tf.write('''>SEQUENCE_1
-    ... MTEITAAMVKELRESTGAGMMDCK
-    ... >SEQUENCE_2
-    ... SATVSEINSETDFVAKN'''.encode('utf8'))
-    66
-    >>> tf.seek(0)
-    0
-
-    >>> df = pd.DataFrame({"sequence_accession":
-    ... ["SEQUENCE_1", "SEQUENCE_2", ]})
-
-    >>> df = df.join_fasta(
-    ...     filename=tf.name,
-    ...     id_col='sequence_accession',
-    ...     column_name='sequence',
-    ... )
-
-    >>> df.sequence
-    0    MTEITAAMVKELRESTGAGMMDCK
-    1           SATVSEINSETDFVAKN
-    Name: sequence, dtype: object
+        >>> import tempfile
+        >>> import pandas as pd
+        >>> import janitor.biology
+
+        >>> tf = tempfile.NamedTemporaryFile()
+        >>> tf.write('''>SEQUENCE_1
+        ... MTEITAAMVKELRESTGAGMMDCK
+        ... >SEQUENCE_2
+        ... SATVSEINSETDFVAKN'''.encode('utf8'))
+        66
+        >>> tf.seek(0)
+        0
+
+        >>> df = pd.DataFrame({"sequence_accession":
+        ... ["SEQUENCE_1", "SEQUENCE_2", ]})
+
+        >>> df = df.join_fasta(
+        ...     filename=tf.name,
+        ...     id_col='sequence_accession',
+        ...     column_name='sequence',
+        ... )
+
+        >>> df.sequence
+        0    MTEITAAMVKELRESTGAGMMDCK
+        1           SATVSEINSETDFVAKN
+        Name: sequence, dtype: object
 
     :param df: A pandas DataFrame.
     :param filename: Path to the FASTA file.
diff --git a/janitor/chemistry.py b/janitor/chemistry.py
--- a/janitor/chemistry.py
+++ b/janitor/chemistry.py
@@ -94,34 +94,34 @@ def smiles2mol(
 
     Functional usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
+        >>> import pandas as pd
+        >>> import janitor.chemistry
 
-    >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
+        >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
 
-    >>> df = janitor.chemistry.smiles2mol(
-    ...    df=df,
-    ...    smiles_column_name='smiles',
-    ...    mols_column_name='mols'
-    ... )
+        >>> df = janitor.chemistry.smiles2mol(
+        ...    df=df,
+        ...    smiles_column_name='smiles',
+        ...    mols_column_name='mols'
+        ... )
 
-    >>> df.mols[0].GetNumAtoms(), df.mols[0].GetNumBonds()
-    (3, 2)
-    >>> df.mols[1].GetNumAtoms(), df.mols[1].GetNumBonds()
-    (5, 4)
+        >>> df.mols[0].GetNumAtoms(), df.mols[0].GetNumBonds()
+        (3, 2)
+        >>> df.mols[1].GetNumAtoms(), df.mols[1].GetNumBonds()
+        (5, 4)
 
     Method chaining usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
+        >>> import pandas as pd
+        >>> import janitor.chemistry
 
-    >>> df = df.smiles2mol(
-    ...     smiles_column_name='smiles',
-    ...     mols_column_name='rdkmol'
-    ... )
+        >>> df = df.smiles2mol(
+        ...     smiles_column_name='smiles',
+        ...     mols_column_name='rdkmol'
+        ... )
 
-    >>> df.rdkmol[0].GetNumAtoms(), df.rdkmol[0].GetNumBonds()
-    (3, 2)
+        >>> df.rdkmol[0].GetNumAtoms(), df.rdkmol[0].GetNumBonds()
+        (3, 2)
 
     A progressbar can be optionally used.
 
@@ -184,78 +184,78 @@ def morgan_fingerprint(
 
     Functional usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
+        >>> import pandas as pd
+        >>> import janitor.chemistry
 
-    >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
+        >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
 
-    # For "counts" kind
-    >>> morgans = janitor.chemistry.morgan_fingerprint(
-    ...     df=df.smiles2mol('smiles', 'mols'),
-    ...     mols_column_name='mols',
-    ...     radius=3,      # Defaults to 3
-    ...     nbits=2048,    # Defaults to 2048
-    ...     kind='counts'  # Defaults to "counts"
-    ... )
+        # For "counts" kind
+        >>> morgans = janitor.chemistry.morgan_fingerprint(
+        ...     df=df.smiles2mol('smiles', 'mols'),
+        ...     mols_column_name='mols',
+        ...     radius=3,      # Defaults to 3
+        ...     nbits=2048,    # Defaults to 2048
+        ...     kind='counts'  # Defaults to "counts"
+        ... )
 
-    >>> set(morgans.iloc[0])
-    {0.0, 1.0, 2.0}
+        >>> set(morgans.iloc[0])
+        {0.0, 1.0, 2.0}
 
-    # For "bits" kind
-    >>> morgans = janitor.chemistry.morgan_fingerprint(
-    ...     df=df.smiles2mol('smiles', 'mols'),
-    ...     mols_column_name='mols',
-    ...     radius=3,      # Defaults to 3
-    ...     nbits=2048,    # Defaults to 2048
-    ...     kind='bits'    # Defaults to "counts"
-    ...  )
+        # For "bits" kind
+        >>> morgans = janitor.chemistry.morgan_fingerprint(
+        ...     df=df.smiles2mol('smiles', 'mols'),
+        ...     mols_column_name='mols',
+        ...     radius=3,      # Defaults to 3
+        ...     nbits=2048,    # Defaults to 2048
+        ...     kind='bits'    # Defaults to "counts"
+        ...  )
 
-    >>> set(morgans.iloc[0])
-    {0.0, 1.0}
+        >>> set(morgans.iloc[0])
+        {0.0, 1.0}
 
     Method chaining usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
-
-    >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
-
-    # For "counts" kind
-    >>> morgans = (
-    ...     df.smiles2mol('smiles', 'mols')
-    ...     .morgan_fingerprint(
-    ...         mols_column_name='mols',
-    ...         radius=3,      # Defaults to 3
-    ...         nbits=2048,    # Defaults to 2048
-    ...         kind='counts'  # Defaults to "counts"
-    ...     )
-    ... )
-
-    >>> set(morgans.iloc[0])
-    {0.0, 1.0, 2.0}
-
-    # For "bits" kind
-    >>> morgans = (
-    ...     df
-    ...     .smiles2mol('smiles', 'mols')
-    ...     .morgan_fingerprint(
-    ...         mols_column_name='mols',
-    ...         radius=3,    # Defaults to 3
-    ...         nbits=2048,  # Defaults to 2048
-    ...         kind='bits'  # Defaults to "counts"
-    ...     )
-    ... )
-
-    >>> set(morgans.iloc[0])
-    {0.0, 1.0}
+        >>> import pandas as pd
+        >>> import janitor.chemistry
+
+        >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
+
+        # For "counts" kind
+        >>> morgans = (
+        ...     df.smiles2mol('smiles', 'mols')
+        ...     .morgan_fingerprint(
+        ...         mols_column_name='mols',
+        ...         radius=3,      # Defaults to 3
+        ...         nbits=2048,    # Defaults to 2048
+        ...         kind='counts'  # Defaults to "counts"
+        ...     )
+        ... )
+
+        >>> set(morgans.iloc[0])
+        {0.0, 1.0, 2.0}
+
+        # For "bits" kind
+        >>> morgans = (
+        ...     df
+        ...     .smiles2mol('smiles', 'mols')
+        ...     .morgan_fingerprint(
+        ...         mols_column_name='mols',
+        ...         radius=3,    # Defaults to 3
+        ...         nbits=2048,  # Defaults to 2048
+        ...         kind='bits'  # Defaults to "counts"
+        ...     )
+        ... )
+
+        >>> set(morgans.iloc[0])
+        {0.0, 1.0}
 
     If you wish to join the morgan fingerprints back into the original
     dataframe, this can be accomplished by doing a `join`,
     because the indices are preserved:
 
-    >>> joined = df.join(morgans)
-    >>> len(joined.columns)
-    2050
+        >>> joined = df.join(morgans)
+        >>> len(joined.columns)
+        2050
 
     :param df: A pandas DataFrame.
     :param mols_column_name: The name of the column that has the RDKIT
@@ -324,47 +324,47 @@ def molecular_descriptors(
 
     Functional usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
+        >>> import pandas as pd
+        >>> import janitor.chemistry
 
-    >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
+        >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
 
-    >>> mol_desc = (
-    ...     janitor.chemistry.molecular_descriptors(
-    ...         df=df.smiles2mol('smiles', 'mols'),
-    ...         mols_column_name='mols'
-    ...     )
-    ... )
+        >>> mol_desc = (
+        ...     janitor.chemistry.molecular_descriptors(
+        ...         df=df.smiles2mol('smiles', 'mols'),
+        ...         mols_column_name='mols'
+        ...     )
+        ... )
 
-    >>> mol_desc.TPSA
-    0    34.14
-    1    37.30
-    Name: TPSA, dtype: float64
+        >>> mol_desc.TPSA
+        0    34.14
+        1    37.30
+        Name: TPSA, dtype: float64
 
     Method chaining usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
+        >>> import pandas as pd
+        >>> import janitor.chemistry
 
-    >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
+        >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
 
-    >>> mol_desc = (
-    ...     df.smiles2mol('smiles', 'mols')
-    ...     .molecular_descriptors(mols_column_name='mols')
-    ... )
+        >>> mol_desc = (
+        ...     df.smiles2mol('smiles', 'mols')
+        ...     .molecular_descriptors(mols_column_name='mols')
+        ... )
 
-    >>> mol_desc.TPSA
-    0    34.14
-    1    37.30
-    Name: TPSA, dtype: float64
+        >>> mol_desc.TPSA
+        0    34.14
+        1    37.30
+        Name: TPSA, dtype: float64
 
     If you wish to join the molecular descriptors back into the original
     dataframe, this can be accomplished by doing a `join`,
     because the indices are preserved:
 
-    >>> joined = df.join(mol_desc)
-    >>> len(joined.columns)
-    41
+        >>> joined = df.join(mol_desc)
+        >>> len(joined.columns)
+        41
 
     :param df: A pandas DataFrame.
     :param mols_column_name: The name of the column that has the RDKIT mol
@@ -435,33 +435,33 @@ def maccs_keys_fingerprint(
 
     Functional usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
+        >>> import pandas as pd
+        >>> import janitor.chemistry
 
-    >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
+        >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
 
-    >>> maccs = janitor.chemistry.maccs_keys_fingerprint(
-    ...     df=df.smiles2mol('smiles', 'mols'),
-    ...     mols_column_name='mols'
-    ... )
+        >>> maccs = janitor.chemistry.maccs_keys_fingerprint(
+        ...     df=df.smiles2mol('smiles', 'mols'),
+        ...     mols_column_name='mols'
+        ... )
 
-    >>> len(maccs.columns)
-    167
+        >>> len(maccs.columns)
+        167
 
     Method chaining usage example:
 
-    >>> import pandas as pd
-    >>> import janitor.chemistry
+        >>> import pandas as pd
+        >>> import janitor.chemistry
 
-    >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
+        >>> df = pd.DataFrame({"smiles": ["O=C=O", "CCC(=O)O"]})
 
-    >>> maccs = (
-    ...     df.smiles2mol('smiles', 'mols')
-    ...         .maccs_keys_fingerprint(mols_column_name='mols')
-    ... )
+        >>> maccs = (
+        ...     df.smiles2mol('smiles', 'mols')
+        ...         .maccs_keys_fingerprint(mols_column_name='mols')
+        ... )
 
-    >>> len(maccs.columns)
-    167
+        >>> len(maccs.columns)
+        167
 
     If you wish to join the maccs keys fingerprints back into the
     original dataframe, this can be accomplished by doing a `join`,
diff --git a/janitor/engineering.py b/janitor/engineering.py
--- a/janitor/engineering.py
+++ b/janitor/engineering.py
@@ -36,20 +36,22 @@ def convert_units(
 
     Method chaining usage example:
 
-    ```python
-    >>> import pandas as pd
-    >>> import janitor.engineering
-    >>> df = pd.DataFrame({"temp_F": [-40, 112]})
-    >>> df = df.convert_units(
-    ...     column_name='temp_F',
-    ...     existing_units='degF',
-    ...     to_units='degC',
-    ...     dest_column_name='temp_C'
-    ... )
-    >>> df
-       temp_F     temp_C
-    0     -40 -40.000000
-    1     112  44.444444
+    Example:
+
+        >>> import pandas as pd
+        >>> import janitor.engineering
+        >>> df = pd.DataFrame({"temp_F": [-40, 112]})
+        >>> df = df.convert_units(
+        ...     column_name='temp_F',
+        ...     existing_units='degF',
+        ...     to_units='degC',
+        ...     dest_column_name='temp_C'
+        ... )
+        >>> df
+           temp_F     temp_C
+        0     -40 -40.000000
+        1     112  44.444444
+
 
 
     Unit conversion can only take place if the `existing_units` and


Test patch: