Re: [Tutor] Questions about the formatting of docstrings
On 27 Jul 2018 06:34, boB Stepp wrote: I am near the end of reading "Documenting Python Code: A Complete Guide" by James Mertz, found at https://realpython.com/documenting-python-code/ This has led me to a few questions: (1) The author claims that reStructuredText is the official Python documentation standard. Is this true? If yes, is this something I should be doing for my own projects? (2) How would type hints work with this reStructuredText formatting? In part of the author's reStructuredText example he has: [...] :param file_loc: The file location of the spreadsheet :type file_loc: str [...] Hi Bob, Have a look at numpydoc, which works with Sphinx. Numpydoc makes it much easier to read and write docstrings, while they can still be converted into nice looking docs, e.g html. See: https://codeandchaos.wordpress.com/2012/08/09/sphinx-and-numpydoc/ Albert-Jan ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] Questions about the formatting of docstrings
On 07/27/2018 11:23 AM, boB Stepp wrote: > On Fri, Jul 27, 2018 at 12:50 AM Steven D'Aprano wrote: >> >> On Thu, Jul 26, 2018 at 11:34:11PM -0500, boB Stepp wrote: > >>> (1) The author claims that reStructuredText is the official Python >>> documentation standard. Is this true? If yes, is this something I >>> should be doing for my own projects? >> >> Yes, it is true. If you write documentation for the Python standard >> library, they are supposed to be in ReST. Docstrings you read in >> the interactive interpreter often aren't, but the documentation you read >> on the web page has all been automatically generated from ReST text >> files. > > What tool is being used to generate the documentation from the ReST text > files? I'm not sure if Python is still using it, but Sphinx is a popular choice, originally written to handle the Python docs. ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] Questions about the formatting of docstrings
On Fri, Jul 27, 2018 at 12:50 AM Steven D'Aprano wrote: > > On Thu, Jul 26, 2018 at 11:34:11PM -0500, boB Stepp wrote: > > (1) The author claims that reStructuredText is the official Python > > documentation standard. Is this true? If yes, is this something I > > should be doing for my own projects? > > Yes, it is true. If you write documentation for the Python standard > library, they are supposed to be in ReST. Docstrings you read in > the interactive interpreter often aren't, but the documentation you read > on the web page has all been automatically generated from ReST text > files. What tool is being used to generate the documentation from the ReST text files? Thanks! boB ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] Questions about the formatting of docstrings
On Thu, Jul 26, 2018 at 11:34:11PM -0500, boB Stepp wrote: > I am near the end of reading "Documenting Python Code: A Complete > Guide" by James Mertz, found at > https://realpython.com/documenting-python-code/ This has led me to a > few questions: > > (1) The author claims that reStructuredText is the official Python > documentation standard. Is this true? If yes, is this something I > should be doing for my own projects? Yes, it is true. If you write documentation for the Python standard library, they are supposed to be in ReST. Docstrings you read in the interactive interpreter often aren't, but the documentation you read on the web page has all been automatically generated from ReST text files. As for your own projects... *shrug*. Are you planning to automatically build richly formatted PDF and HTML files from plain text documentation? If not, I wouldn't worry too much. On the other hand, if your documentation will benefit from things like: Headings * lists of items * with bullets Definition a concise explanation of the meaning of a word then you're probably already using something close to ReST. > (2) How would type hints work with this reStructuredText formatting? Before Python 3 introduced syntax for type hints: def func(arg: int) -> float: ... there were a number of de facto conventions for coding that information into the function doc string. Being plain text, the human reader can simply read it, but being a standard format, people can write tools to extract that information and process it. Well I say standard format, but in fact there were a number of slightly different competing formats. > In part of the author's reStructuredText example he has: > > [...] > :param file_loc: The file location of the spreadsheet > :type file_loc: str > [...] As far as I remember, that's not part of standard ReST, but an extension used by the Sphinx restructured text tool. I don't know what it does with that information, but being a known format, any tool can parse the docstring, extract out the parameters and their types, and generate documentation, do type checking (either statically or dynamically) or whatever else you want to do. > It seems to me that if type hinting is being used, then the ":type" > info is redundant, so I wonder if special provision is made for > avoiding this redundancy when using type hinting? No. You can use one, or the other, or both, or neither, whatever takes your fancy. I expect that as Python 2 fades away, it will eventually become common practice to document types using a type hint rather than in the docstring and people will simply stop writing things like ":type file_loc: str" in favour of using def func(file_loc: str). -- Steve ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor
[Tutor] Questions about the formatting of docstrings
I am near the end of reading "Documenting Python Code: A Complete Guide" by James Mertz, found at https://realpython.com/documenting-python-code/ This has led me to a few questions: (1) The author claims that reStructuredText is the official Python documentation standard. Is this true? If yes, is this something I should be doing for my own projects? (2) How would type hints work with this reStructuredText formatting? In part of the author's reStructuredText example he has: [...] :param file_loc: The file location of the spreadsheet :type file_loc: str [...] It seems to me that if type hinting is being used, then the ":type" info is redundant, so I wonder if special provision is made for avoiding this redundancy when using type hinting? TIA! -- boB ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor
