DEPR: Positional arguments in Series.to_markdown (pandas-dev#57372)

* Updated whatsnew and added deprecation message.

* Adding unit test for deprecation warning.

* Updating unit tests.

* Update series.py

* Updating unit test and documentation.

* Adding in to_markdown overload functions per reviewer feedback.

* Updating implementation based on reviewer feedback.

Author: rmhowe425

doc/source/whatsnew/v3.0.0.rst

@@ -102,6 +102,7 @@ Deprecations
 ~~~~~~~~~~~~
 - Deprecated :meth:`Timestamp.utcfromtimestamp`, use ``Timestamp.fromtimestamp(ts, "UTC")`` instead (:issue:`56680`)
 - Deprecated :meth:`Timestamp.utcnow`, use ``Timestamp.now("UTC")`` instead (:issue:`56680`)
+- Deprecated allowing non-keyword arguments in :meth:`Series.to_markdown` except ``buf``. (:issue:`57280`)
 - Deprecated allowing non-keyword arguments in :meth:`Series.to_string` except ``buf``. (:issue:`57280`)
 -
 

pandas/core/series.py

@@ -1606,6 +1606,42 @@ def to_string(
                     f.write(result)
         return None
 
+    @overload
+    def to_markdown(
+        self,
+        buf: None = ...,
+        *,
+        mode: str = ...,
+        index: bool = ...,
+        storage_options: StorageOptions | None = ...,
+        **kwargs,
+    ) -> str:
+        ...
+
+    @overload
+    def to_markdown(
+        self,
+        buf: IO[str],
+        *,
+        mode: str = ...,
+        index: bool = ...,
+        storage_options: StorageOptions | None = ...,
+        **kwargs,
+    ) -> None:
+        ...
+
+    @overload
+    def to_markdown(
+        self,
+        buf: IO[str] | None,
+        *,
+        mode: str = ...,
+        index: bool = ...,
+        storage_options: StorageOptions | None = ...,
+        **kwargs,
+    ) -> str | None:
+        ...
+
     @doc(
         klass=_shared_doc_kwargs["klass"],
         storage_options=_shared_docs["storage_options"],
@@ -1637,6 +1673,9 @@ def to_string(
             +----+----------+"""
         ),
     )
+    @deprecate_nonkeyword_arguments(
+        version="3.0.0", allowed_args=["self", "buf"], name="to_markdown"
+    )
     def to_markdown(
         self,
         buf: IO[str] | None = None,

pandas/tests/io/formats/test_to_markdown.py

@@ -3,10 +3,22 @@
 import pytest
 
 import pandas as pd
+import pandas._testing as tm
 
 pytest.importorskip("tabulate")
 
 
+def test_keyword_deprecation():
+    # GH 57280
+    msg = (
+        "Starting with pandas version 3.0.0 all arguments of to_markdown "
+        "except for the argument 'buf' will be keyword-only."
+    )
+    s = pd.Series()
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        s.to_markdown(None, "wt")
+
+
 def test_simple():
     buf = StringIO()
     df = pd.DataFrame([1, 2, 3])