prompt: We are currently solving the following issue within our repository. Here is the issue text:
  --- BEGIN ISSUE ---
  [DOC] Update docs to have timeseries section
  # 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 section for the timeseries module.
  
  I would like to propose a change, such that now the docs will have details on the timerseries functions.
  
  # 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://ericmjl.github.io/pyjanitor/reference/index.html)
  - [Link to exact file to be edited](https://github.com/ericmjl/pyjanitor/blob/dev/docs/reference/index.rst)
  
  
  --- END ISSUE ---
  
  Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
  --- BEGIN FILES ---
  Path: `janitor/timeseries.py`
  Content:
  ```
  1 """
  2 Time series-specific data testing and cleaning functions.
  3 """
  4 
  5 import pandas as pd
  6 import pandas_flavor as pf
  7 
  8 from janitor import check
  9 
  10 
  11 @pf.register_dataframe_method
  12 def fill_missing_timestamps(
  13     df: pd.DataFrame,
  14     frequency: str,
  15     first_time_stamp: pd.Timestamp = None,
  16     last_time_stamp: pd.Timestamp = None,
  17 ) -> pd.DataFrame:
  18     """
  19     Fill dataframe with missing timestamps based on a defined frequency.
  20 
  21     If timestamps are missing,
  22     this function will reindex the dataframe.
  23     If timestamps are not missing,
  24     then the function will return the dataframe unmodified.
  25     Example usage:
  26     .. code-block:: python
  27 
  28         df = (
  29             pd.DataFrame(...)
  30             .fill_missing_timestamps(frequency="1H")
  31         )
  32 
  33     :param df: Dataframe which needs to be tested for missing timestamps
  34     :param frequency: frequency i.e. sampling frequency of the data.
  35         Acceptable frequency strings are available
  36         `here <https://pandas.pydata.org/pandas-docs/stable/>`_
  37         Check offset aliases under time series in user guide
  38     :param first_time_stamp: timestamp expected to start from
  39         Defaults to None.
  40         If no input is provided assumes the minimum value in time_series
  41     :param last_time_stamp: timestamp expected to end with.
  42         Defaults to None.
  43         If no input is provided, assumes the maximum value in time_series
  44     :returns: dataframe that has a complete set of contiguous datetimes.
  45     """
  46     # Check all the inputs are the correct data type
  47     check("frequency", frequency, [str])
  48     check("first_time_stamp", first_time_stamp, [pd.Timestamp, type(None)])
  49     check("last_time_stamp", last_time_stamp, [pd.Timestamp, type(None)])
  50 
  51     if first_time_stamp is None:
  52         first_time_stamp = df.index.min()
  53     if last_time_stamp is None:
  54         last_time_stamp = df.index.max()
  55 
  56     # Generate expected timestamps
  57     expected_timestamps = pd.date_range(
  58         start=first_time_stamp, end=last_time_stamp, freq=frequency
  59     )
  60 
  61     return df.reindex(expected_timestamps)
  62 
  63 
  64 def _get_missing_timestamps(
  65     df: pd.DataFrame,
  66     frequency: str,
  67     first_time_stamp: pd.Timestamp = None,
  68     last_time_stamp: pd.Timestamp = None,
  69 ) -> pd.DataFrame:
  70     """
  71     Return the timestamps that are missing in a dataframe.
  72 
  73     This function takes in a dataframe,
  74     and checks its index against a dataframe
  75     that contains the expected timestamps.
  76     Here, we assume that the expected timestamps
  77     are going to be of a larger size
  78     than the timestamps available in the input dataframe ``df``.
  79 
  80     If there are any missing timestamps in the input dataframe,
  81     this function will return those missing timestamps
  82     from the expected dataframe.
  83     """
  84     expected_df = df.fill_missing_timestamps(
  85         frequency, first_time_stamp, last_time_stamp
  86     )
  87 
  88     missing_timestamps = expected_df.index.difference(df.index)
  89 
  90     return expected_df.loc[missing_timestamps]
  91 
  92 
  93 @pf.register_dataframe_method
  94 def sort_timestamps_monotonically(
  95     df: pd.DataFrame, direction: str = "increasing", strict: bool = False
  96 ) -> pd.DataFrame:
  97     """
  98     Sort dataframe such that index is monotonic.
  99 
  100     If timestamps are monotonic,
  101     this function will return the dataframe unmodified.
  102     If timestamps are not monotonic,
  103     then the function will sort the dataframe.
  104 
  105     Example usage:
  106 
  107     .. code-block:: python
  108 
  109         df = (
  110             pd.DataFrame(...)
  111             .sort_timestamps_monotonically(direction='increasing')
  112         )
  113 
  114     :param df: Dataframe which needs to be tested for monotonicity
  115     :param direction: type of monotonicity desired.
  116         Acceptable arguments are:
  117             1. increasing
  118             2. decreasing
  119     :param strict: flag to enable/disable strict monotonicity.
  120         If set to True,
  121         will remove duplicates in the index,
  122         by retaining first occurrence of value in index.
  123         If set to False,
  124         will not test for duplicates in the index.
  125         Defaults to False.
  126     :returns: Dataframe that has monotonically increasing
  127         (or decreasing) timestamps.
  128     """
  129     # Check all the inputs are the correct data type
  130     check("df", df, [pd.DataFrame])
  131     check("direction", direction, [str])
  132     check("strict", strict, [bool])
  133 
  134     # Remove duplicates if requested
  135     if strict:
  136         df = df[~df.index.duplicated(keep="first")]
  137 
  138     # Sort timestamps
  139     if direction == "increasing":
  140         df = df.sort_index()
  141     else:
  142         df = df.sort_index(ascending=False)
  143 
  144     # Return the dataframe
  145     return df
  146
  ```
  --- END FILES ---
  
  Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.
  
  Here is an example:
  
  ```diff
  diff --git a/examples/server_async.py b/examples/server_async.py
  --- a/examples/server_async.py
  +++ b/examples/server_async.py
  @@ -313,4 +313,4 @@
   
   
   if __name__ == "__main__":
  -    asyncio.run(run_async_server("."), debug=True)
  +    asyncio.run(run_async_server(), debug=True)
  diff --git a/examples/server_sync.py b/examples/server_sync.py
  --- a/examples/server_sync.py
  +++ b/examples/server_sync.py
  @@ -313,5 +313,5 @@
   
   
   if __name__ == "__main__":
  -    server = run_sync_server(".")
  +    server = run_sync_server()
       server.shutdown()
  
  ```
  
golden_diff: diff --git a/janitor/timeseries.py b/janitor/timeseries.py
  --- a/janitor/timeseries.py
  +++ b/janitor/timeseries.py
  @@ -1,6 +1,4 @@
  -"""
  -Time series-specific data testing and cleaning functions.
  -"""
  +""" Time series-specific data cleaning functions. """
   
   import pandas as pd
   import pandas_flavor as pf
  @@ -22,9 +20,28 @@
       this function will reindex the dataframe.
       If timestamps are not missing,
       then the function will return the dataframe unmodified.
  -    Example usage:
  +
  +    Functional usage example:
  +
  +    .. code-block:: python
  +
  +        import pandas as pd
  +        import janitor.timeseries
  +
  +        df = pd.DataFrame(...)
  +
  +        df = janitor.timeseries.fill_missing_timestamps(
  +            df=df,
  +            frequency="1H",
  +        )
  +
  +    Method chaining example:
  +
       .. code-block:: python
   
  +        import pandas as pd
  +        import janitor.timeseries
  +
           df = (
               pd.DataFrame(...)
               .fill_missing_timestamps(frequency="1H")
  @@ -102,13 +119,29 @@
       If timestamps are not monotonic,
       then the function will sort the dataframe.
   
  -    Example usage:
  +    Functional usage example:
   
       .. code-block:: python
   
  +        import pandas as pd
  +        import janitor.timeseries
  +
  +        df = pd.DataFrame(...)
  +
  +        df = janitor.timeseries.sort_timestamps_monotonically(
  +            direction="increasing"
  +        )
  +
  +    Method chaining example:
  +
  +    .. code-block:: python
  +
  +        import pandas as pd
  +        import janitor.timeseries
  +
           df = (
               pd.DataFrame(...)
  -            .sort_timestamps_monotonically(direction='increasing')
  +            .sort_timestamps_monotonically(direction="increasing")
           )
   
       :param df: Dataframe which needs to be tested for monotonicity
  
verification_info: {"golden_diff": "diff --git a/janitor/timeseries.py b/janitor/timeseries.py\n--- a/janitor/timeseries.py\n+++ b/janitor/timeseries.py\n@@ -1,6 +1,4 @@\n-\"\"\"\n-Time series-specific data testing and cleaning functions.\n-\"\"\"\n+\"\"\" Time series-specific data cleaning functions. \"\"\"\n \n import pandas as pd\n import pandas_flavor as pf\n@@ -22,9 +20,28 @@\n     this function will reindex the dataframe.\n     If timestamps are not missing,\n     then the function will return the dataframe unmodified.\n-    Example usage:\n+\n+    Functional usage example:\n+\n+    .. code-block:: python\n+\n+        import pandas as pd\n+        import janitor.timeseries\n+\n+        df = pd.DataFrame(...)\n+\n+        df = janitor.timeseries.fill_missing_timestamps(\n+            df=df,\n+            frequency=\"1H\",\n+        )\n+\n+    Method chaining example:\n+\n     .. code-block:: python\n \n+        import pandas as pd\n+        import janitor.timeseries\n+\n         df = (\n             pd.DataFrame(...)\n             .fill_missing_timestamps(frequency=\"1H\")\n@@ -102,13 +119,29 @@\n     If timestamps are not monotonic,\n     then the function will sort the dataframe.\n \n-    Example usage:\n+    Functional usage example:\n \n     .. code-block:: python\n \n+        import pandas as pd\n+        import janitor.timeseries\n+\n+        df = pd.DataFrame(...)\n+\n+        df = janitor.timeseries.sort_timestamps_monotonically(\n+            direction=\"increasing\"\n+        )\n+\n+    Method chaining example:\n+\n+    .. code-block:: python\n+\n+        import pandas as pd\n+        import janitor.timeseries\n+\n         df = (\n             pd.DataFrame(...)\n-            .sort_timestamps_monotonically(direction='increasing')\n+            .sort_timestamps_monotonically(direction=\"increasing\")\n         )\n \n     :param df: Dataframe which needs to be tested for monotonicity\n", "issue": "[DOC] Update docs to have timeseries section\n# Brief Description of Fix\r\n\r\n<!-- Please describe the fix in terms of a \"before\" and \"after\". In other words, what's not so good about the current docs\r\npage, and what you would like to see it become.\r\n\r\nExample starter wording is provided. -->\r\n\r\nCurrently, the docs do not have a section for the timeseries module.\r\n\r\nI would like to propose a change, such that now the docs will have details on the timerseries functions.\r\n\r\n# Relevant Context\r\n\r\n<!-- Please put here, in bullet points, links to the relevant docs page. A few starting template points are available\r\nto get you started. -->\r\n\r\n- [Link to documentation page](https://ericmjl.github.io/pyjanitor/reference/index.html)\r\n- [Link to exact file to be edited](https://github.com/ericmjl/pyjanitor/blob/dev/docs/reference/index.rst)\r\n\n", "before_files": [{"content": "\"\"\"\nTime series-specific data testing and cleaning functions.\n\"\"\"\n\nimport pandas as pd\nimport pandas_flavor as pf\n\nfrom janitor import check\n\n\n@pf.register_dataframe_method\ndef fill_missing_timestamps(\n    df: pd.DataFrame,\n    frequency: str,\n    first_time_stamp: pd.Timestamp = None,\n    last_time_stamp: pd.Timestamp = None,\n) -> pd.DataFrame:\n    \"\"\"\n    Fill dataframe with missing timestamps based on a defined frequency.\n\n    If timestamps are missing,\n    this function will reindex the dataframe.\n    If timestamps are not missing,\n    then the function will return the dataframe unmodified.\n    Example usage:\n    .. code-block:: python\n\n        df = (\n            pd.DataFrame(...)\n            .fill_missing_timestamps(frequency=\"1H\")\n        )\n\n    :param df: Dataframe which needs to be tested for missing timestamps\n    :param frequency: frequency i.e. sampling frequency of the data.\n        Acceptable frequency strings are available\n        `here <https://pandas.pydata.org/pandas-docs/stable/>`_\n        Check offset aliases under time series in user guide\n    :param first_time_stamp: timestamp expected to start from\n        Defaults to None.\n        If no input is provided assumes the minimum value in time_series\n    :param last_time_stamp: timestamp expected to end with.\n        Defaults to None.\n        If no input is provided, assumes the maximum value in time_series\n    :returns: dataframe that has a complete set of contiguous datetimes.\n    \"\"\"\n    # Check all the inputs are the correct data type\n    check(\"frequency\", frequency, [str])\n    check(\"first_time_stamp\", first_time_stamp, [pd.Timestamp, type(None)])\n    check(\"last_time_stamp\", last_time_stamp, [pd.Timestamp, type(None)])\n\n    if first_time_stamp is None:\n        first_time_stamp = df.index.min()\n    if last_time_stamp is None:\n        last_time_stamp = df.index.max()\n\n    # Generate expected timestamps\n    expected_timestamps = pd.date_range(\n        start=first_time_stamp, end=last_time_stamp, freq=frequency\n    )\n\n    return df.reindex(expected_timestamps)\n\n\ndef _get_missing_timestamps(\n    df: pd.DataFrame,\n    frequency: str,\n    first_time_stamp: pd.Timestamp = None,\n    last_time_stamp: pd.Timestamp = None,\n) -> pd.DataFrame:\n    \"\"\"\n    Return the timestamps that are missing in a dataframe.\n\n    This function takes in a dataframe,\n    and checks its index against a dataframe\n    that contains the expected timestamps.\n    Here, we assume that the expected timestamps\n    are going to be of a larger size\n    than the timestamps available in the input dataframe ``df``.\n\n    If there are any missing timestamps in the input dataframe,\n    this function will return those missing timestamps\n    from the expected dataframe.\n    \"\"\"\n    expected_df = df.fill_missing_timestamps(\n        frequency, first_time_stamp, last_time_stamp\n    )\n\n    missing_timestamps = expected_df.index.difference(df.index)\n\n    return expected_df.loc[missing_timestamps]\n\n\n@pf.register_dataframe_method\ndef sort_timestamps_monotonically(\n    df: pd.DataFrame, direction: str = \"increasing\", strict: bool = False\n) -> pd.DataFrame:\n    \"\"\"\n    Sort dataframe such that index is monotonic.\n\n    If timestamps are monotonic,\n    this function will return the dataframe unmodified.\n    If timestamps are not monotonic,\n    then the function will sort the dataframe.\n\n    Example usage:\n\n    .. code-block:: python\n\n        df = (\n            pd.DataFrame(...)\n            .sort_timestamps_monotonically(direction='increasing')\n        )\n\n    :param df: Dataframe which needs to be tested for monotonicity\n    :param direction: type of monotonicity desired.\n        Acceptable arguments are:\n            1. increasing\n            2. decreasing\n    :param strict: flag to enable/disable strict monotonicity.\n        If set to True,\n        will remove duplicates in the index,\n        by retaining first occurrence of value in index.\n        If set to False,\n        will not test for duplicates in the index.\n        Defaults to False.\n    :returns: Dataframe that has monotonically increasing\n        (or decreasing) timestamps.\n    \"\"\"\n    # Check all the inputs are the correct data type\n    check(\"df\", df, [pd.DataFrame])\n    check(\"direction\", direction, [str])\n    check(\"strict\", strict, [bool])\n\n    # Remove duplicates if requested\n    if strict:\n        df = df[~df.index.duplicated(keep=\"first\")]\n\n    # Sort timestamps\n    if direction == \"increasing\":\n        df = df.sort_index()\n    else:\n        df = df.sort_index(ascending=False)\n\n    # Return the dataframe\n    return df\n", "path": "janitor/timeseries.py"}], "after_files": [{"content": "\"\"\" Time series-specific data cleaning functions. \"\"\"\n\nimport pandas as pd\nimport pandas_flavor as pf\n\nfrom janitor import check\n\n\n@pf.register_dataframe_method\ndef fill_missing_timestamps(\n    df: pd.DataFrame,\n    frequency: str,\n    first_time_stamp: pd.Timestamp = None,\n    last_time_stamp: pd.Timestamp = None,\n) -> pd.DataFrame:\n    \"\"\"\n    Fill dataframe with missing timestamps based on a defined frequency.\n\n    If timestamps are missing,\n    this function will reindex the dataframe.\n    If timestamps are not missing,\n    then the function will return the dataframe unmodified.\n\n    Functional usage example:\n\n    .. code-block:: python\n\n        import pandas as pd\n        import janitor.timeseries\n\n        df = pd.DataFrame(...)\n\n        df = janitor.timeseries.fill_missing_timestamps(\n            df=df,\n            frequency=\"1H\",\n        )\n\n    Method chaining example:\n\n    .. code-block:: python\n\n        import pandas as pd\n        import janitor.timeseries\n\n        df = (\n            pd.DataFrame(...)\n            .fill_missing_timestamps(frequency=\"1H\")\n        )\n\n    :param df: Dataframe which needs to be tested for missing timestamps\n    :param frequency: frequency i.e. sampling frequency of the data.\n        Acceptable frequency strings are available\n        `here <https://pandas.pydata.org/pandas-docs/stable/>`_\n        Check offset aliases under time series in user guide\n    :param first_time_stamp: timestamp expected to start from\n        Defaults to None.\n        If no input is provided assumes the minimum value in time_series\n    :param last_time_stamp: timestamp expected to end with.\n        Defaults to None.\n        If no input is provided, assumes the maximum value in time_series\n    :returns: dataframe that has a complete set of contiguous datetimes.\n    \"\"\"\n    # Check all the inputs are the correct data type\n    check(\"frequency\", frequency, [str])\n    check(\"first_time_stamp\", first_time_stamp, [pd.Timestamp, type(None)])\n    check(\"last_time_stamp\", last_time_stamp, [pd.Timestamp, type(None)])\n\n    if first_time_stamp is None:\n        first_time_stamp = df.index.min()\n    if last_time_stamp is None:\n        last_time_stamp = df.index.max()\n\n    # Generate expected timestamps\n    expected_timestamps = pd.date_range(\n        start=first_time_stamp, end=last_time_stamp, freq=frequency\n    )\n\n    return df.reindex(expected_timestamps)\n\n\ndef _get_missing_timestamps(\n    df: pd.DataFrame,\n    frequency: str,\n    first_time_stamp: pd.Timestamp = None,\n    last_time_stamp: pd.Timestamp = None,\n) -> pd.DataFrame:\n    \"\"\"\n    Return the timestamps that are missing in a dataframe.\n\n    This function takes in a dataframe,\n    and checks its index against a dataframe\n    that contains the expected timestamps.\n    Here, we assume that the expected timestamps\n    are going to be of a larger size\n    than the timestamps available in the input dataframe ``df``.\n\n    If there are any missing timestamps in the input dataframe,\n    this function will return those missing timestamps\n    from the expected dataframe.\n    \"\"\"\n    expected_df = df.fill_missing_timestamps(\n        frequency, first_time_stamp, last_time_stamp\n    )\n\n    missing_timestamps = expected_df.index.difference(df.index)\n\n    return expected_df.loc[missing_timestamps]\n\n\n@pf.register_dataframe_method\ndef sort_timestamps_monotonically(\n    df: pd.DataFrame, direction: str = \"increasing\", strict: bool = False\n) -> pd.DataFrame:\n    \"\"\"\n    Sort dataframe such that index is monotonic.\n\n    If timestamps are monotonic,\n    this function will return the dataframe unmodified.\n    If timestamps are not monotonic,\n    then the function will sort the dataframe.\n\n    Functional usage example:\n\n    .. code-block:: python\n\n        import pandas as pd\n        import janitor.timeseries\n\n        df = pd.DataFrame(...)\n\n        df = janitor.timeseries.sort_timestamps_monotonically(\n            direction=\"increasing\"\n        )\n\n    Method chaining example:\n\n    .. code-block:: python\n\n        import pandas as pd\n        import janitor.timeseries\n\n        df = (\n            pd.DataFrame(...)\n            .sort_timestamps_monotonically(direction=\"increasing\")\n        )\n\n    :param df: Dataframe which needs to be tested for monotonicity\n    :param direction: type of monotonicity desired.\n        Acceptable arguments are:\n            1. increasing\n            2. decreasing\n    :param strict: flag to enable/disable strict monotonicity.\n        If set to True,\n        will remove duplicates in the index,\n        by retaining first occurrence of value in index.\n        If set to False,\n        will not test for duplicates in the index.\n        Defaults to False.\n    :returns: Dataframe that has monotonically increasing\n        (or decreasing) timestamps.\n    \"\"\"\n    # Check all the inputs are the correct data type\n    check(\"df\", df, [pd.DataFrame])\n    check(\"direction\", direction, [str])\n    check(\"strict\", strict, [bool])\n\n    # Remove duplicates if requested\n    if strict:\n        df = df[~df.index.duplicated(keep=\"first\")]\n\n    # Sort timestamps\n    if direction == \"increasing\":\n        df = df.sort_index()\n    else:\n        df = df.sort_index(ascending=False)\n\n    # Return the dataframe\n    return df\n", "path": "janitor/timeseries.py"}]}