docs: fix regression with incorrect args order in docs (#1141)

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [x] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/google-api-python-client/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [x] Ensure the tests and linter pass
- [x] Code coverage does not decrease (if any source code was changed)
- [x] Appropriate docs were updated (if necessary)

Fixes #1140  🦕

1 files changed, 10 insertions, 4 deletions

diff --git a/describe.py b/describe.py
index 0b7d10f3d..3d9d7a46a 100755
--- a/describe.py
+++ b/describe.py
@@ -215,6 +215,7 @@ def method_params(doc):
             args = doclines[begin + 1 :]
 
         parameters = []
+        sorted_parameters = []
         pname = None
         desc = ""
 
@@ -223,7 +224,11 @@ def method_params(doc):
                 return
             if "(required)" not in desc:
                 pname = pname + "=None"
-            parameters.append(pname)
+                parameters.append(pname)
+            else:
+                # required params should be put straight into sorted_parameters
+                # to maintain order for positional args
+                sorted_parameters.append(pname)
 
         for line in args:
             m = re.search(r"^\s+([a-zA-Z0-9_]+): (.*)", line)
@@ -234,10 +239,11 @@ def method_params(doc):
             pname = m.group(1)
             desc = m.group(2)
         add_param(pname, desc)
-        parameters = ", ".join(sorted(parameters))
+        sorted_parameters.extend(sorted(parameters))
+        sorted_parameters = ", ".join(sorted_parameters)
     else:
-        parameters = ""
-    return parameters
+        sorted_parameters = ""
+    return sorted_parameters
 
 
 def method(name, doc):