DOC: parameterize "See Also" content in read_table and read_csv so that only the other function appears

[tpaxman]

• closes DOC: read_csv docstring incorrectly references itself in the "See Also" section #53847
• All code checks passed.

Note: this was the least invasive way to update it and I think it's probably sufficient. The only duplication introduced would be repeating the "summary" lines for each of the functions. If that were a concern, I would suggest making another update where the docstring string formatting parameters are abstracted away once more by introducing something like this:

Define this function in the file:

def _generate_docstring_formatter(func_name: Literal["read_csv", "read_table"]) -> dict:
    func_details = {
        "read_csv": {
            "summary": "Read a comma-separated values (csv) file into DataFrame.",
            "_default_sep": "','",
        },
        "read_table": {
            "summary": "Read general delimited file into DataFrame.",
            "_default_sep": r"'\\t' (tab-stop)",
        }
    }
    see_also_func_name = "read_table" if (func_name == "read_csv") else "read_csv"
    return dict(
        func_name=func_name,
        summary=func_details[func_name]["summary"],
        _default_sep=func_details[func_name]["_default_sep"],
        see_also_func_name=see_also_func_name,
        see_also_func_summary=func_details[see_also_func_name]["summary"],
        storage_options=_shared_docs["storage_options"],
        decompression_options=_shared_docs["decompression_options"]
        % "filepath_or_buffer",
    )

Then replace the two @Appender decorator calls with these instead:

# for read_csv:
@Appender(_doc_read_csv_and_table.format(**_generate_docstring_formatter("read_csv")))

# for read_table:
@Appender(_doc_read_csv_and_table.format(**_generate_docstring_formatter("read_table")))

I have tested this and it also works but I was unsure whether it's worthwhile (in the maintainers' view) to make that change to avoid a one-line duplication case. Curious to hear feedback though!

[mroeschke]

Thanks @tpaxman