Hello, I'm wondering if people have suggestions on the best way to format function/method docstrings so it's possible to get Sphinx's fancy formatting and yet retain nice and readable docstrings from the Python prompt. I'm especially interested in how to document the function/ method input "parameters".
I know about the :param name: stanza but when there's a relatively long list of parameters, I don't find it very readable from the Python prompt. Of course, once processed by Sphinx, it yields great looking documentation. I also know about http://packages.python.org/an_example_pypi_project/sphinx.html and the googley and sphinxey variants. I'm thinking there must be a good compromise here. For return values, I often use the following in my docstrings: :returns: :out1: something :out2: something else Indentation and proper alignment make this easy to read *and* it looks great once processed by Sphinx. But I can't find a similar syntax for parameters and keywords. I *thought* (and obviously I'm wrong) that Sphinx accepted :parameters: and :keywords: but those don't look nice once processed, e.g., to html. In particular, :parameters: is converted to "Parameters :" (with a space), which often causes the colon to end on a new line below the word "Parameters". It would be great to be able to write: :parameters: :in1: description of in1 :in2: description of in2 :keywords: :kw1: description of kw1 just the same way we can use :returns:. I'm happy to try and add this if it sounds like a good idea. I'd like to hear what people think anyways. Thanks. -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
