RunSQL documentation is incorrect

[Flavio Curella]

The current documentation for the RunSQL operation includes the following example:

migrations.RunSQL(["INSERT INTO musician (name) VALUES (%s);", ['Reinhardt']])

That didn't work for me. The code that actually executes the replacement, in django.db.migrations.operations.special.RunSQL._run_sql is:

    def _run_sql(self, schema_editor, sqls):
        if isinstance(sqls, (list, tuple)):
            for sql in sqls:
                params = None
                if isinstance(sql, (list, tuple)):
                    elements = len(sql)
                    if elements == 2:
                        sql, params = sql
                    else:
                        raise ValueError("Expected a 2-tuple but got %d" % elements)
                schema_editor.execute(sql, params=params)

If I'm reading the code correctly, the provided example should instead be:

migrations.RunSQL([["INSERT INTO musician (name) VALUES (%s);", ['Reinhardt']]])

Indeed, I've found this very same usage in the tests (tests/migrations/test_operations.py:test_run_sql_params@L1541):

        param_operation = migrations.RunSQL(
            # forwards
            (
                "INSERT INTO i_love_ponies (id, special_thing) VALUES (1, 'Django');",
                ["INSERT INTO i_love_ponies (id, special_thing) VALUES (2, %s);", ['Ponies']],
                ("INSERT INTO i_love_ponies (id, special_thing) VALUES (%s, %s);", (3, 'Python',)),
            ),
            # backwards
            [
                "DELETE FROM i_love_ponies WHERE special_thing = 'Django';",
                ["DELETE FROM i_love_ponies WHERE special_thing = 'Ponies';", None],
                ("DELETE FROM i_love_ponies WHERE id = %s OR special_thing = %s;", [3, 'Python']),
            ]
        )

Looking throughout the docs, I could not find any usage such as the one referred in the doc. That is value replacement where the sql is a list made of SQL statement + the list params. The only usage I could find are instances of list of list of SQL + params.