René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Consistent Documentation Guide for Docstrings","articleBody":"### Bug report\r\n\r\n**Summary**\r\n\r\nThe [documentation guide](http://matplotlib.org/devdocs/devel/documenting_mpl.html#documenting-matplotlib) contains a section about docstrings. Unfortunately, in my attempt to add / improve some docstrings I found it largely deficient.\r\n\r\nThis issue collects the problems I encounted and may serve as a starting point to improve the API docs.\r\n\r\n**Motivation**\r\n\r\nA good documentation is essentially for the usability of a library. Even more so, for a large library with many options and making heavy use of `*args` and `**kwargs`.\r\n\r\nTo get improvements here, there has to be a *consistent and easily understandable style guide*. Otherwise, contributors will not know or bother.\r\n\r\n**Issues**\r\n\r\n1. **Multiple sources**\r\n\r\n* the  [documentation guide](http://matplotlib.org/devdocs/devel/documenting_mpl.html#documenting-matplotlib)\r\n* [Numpy: How to document](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)\r\n* The pending #9513 was pointed out to me as an additional source, however I don't think it says anything about docstrings.\r\n* There are some rules discussed or decided in issues, e.g. #8079 on quotes, #7535,  #6924 on Other Parameters\r\n\r\n- [ ] Include all information in the [docstrings section](http://matplotlib.org/devdocs/devel/documenting_mpl.html#docstrings), reference numpydoc docmentation.\r\n\r\n2. **Outdated directions**\r\n\r\nThe [docstrings section](http://matplotlib.org/devdocs/devel/documenting_mpl.html#docstrings) is outdated and thus misleading.\r\n\r\n\u003e In addition to the “narrative” documentation described above, matplotlib also defines its API reference documentation in docstrings. For the most part, these are standard Python docstrings, but matplotlib also includes some features to better support documenting getters and setters.\r\n\r\nbetter:\r\n\r\n\u003e In addition to the “narrative” documentation described above, the API reference documentation is generated from docstrings in the code. Generally, matplotlib uses numpy style docstrings [link]. To further enhance the documentation we have augmented numpy style by some additional conventions and features.\r\n\u003e \r\n\u003e Additional Conventions:\r\n\u003e \r\n\u003e Additional Features: [existing stuff here]\r\n\r\n- [ ] Remove outdated stuff. Add placeholders and notes if there are some known gaps.\r\n\r\n3. **Additional Conventions**\r\n\r\nnumpydoc does not fully cover all aspects of docstrings. Some should be clarified on the project level.\r\n\r\n- Handling of `*args` and `**kwargs`: Should they be Parameters, Other Parameters or something else?\r\n\r\n- Handling of long lists of value choices:\r\n\r\n[See here](https://github.com/matplotlib/matplotlib/pull/9777#pullrequestreview-76296627):\r\n```\r\nprojection :\r\n            ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \\\r\n'polar' | 'rectilinear'], optional\r\n```\r\n\r\n- When to use *abc*, `abc`, 'abc', \"abc\", ``abc``. In particular also usage of double or single quotes in the docs (even if it's: Do as you like but don't change existing stuff). Indicate if these decisions deviate intentionally from other sources you link (e.g. [numpy](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt): \"Variable, module, function, and class names should be written between single back-ticks (`numpy`)\", vs [Formatting](http://matplotlib.org/devdocs/devel/documenting_mpl.html#formatting): \"Function arguments and keywords should be referred to using the emphasis role.\"\r\n\r\n- When to cross reference and when not  \"Types don't need to be marked up.\" vs \"Sometimes sphinx doesn't automatically put in links with out the markup though.\" [See here](https://github.com/matplotlib/matplotlib/pull/9777#pullrequestreview-76296627) Also if sphinx has a bug that return values are not always cross-referenced, mention that and your policy (Either keep plain types, it will be fine once sphinx is fixed. Or add reference now, we can strip it later).\r\n\r\n- Usage of call signature: Some methods have this, others not.\r\n\r\n~~~\r\n    Call signature::\r\n\r\n      text(x, y, s, fontdict=None, **kwargs)\r\n~~~\r\n\r\n4. **Migration of documentation**\r\n\r\n- [ ] State that there's still a mixture of old and new styles and that the migration is ongoing.\r\n- [ ] List deprecated conventions and how to replace them.\r\n\r\n5. **Examples**\r\n\r\n- [ ] Add examples in the above parts as much as possible. They are more instructure than lengthy texts.\r\n- [ ] Link to parts of code with good documentation, from which one can learn.\r\n\r\n\r\n","author":{"url":"https://github.com/timhoffm","@type":"Person","name":"timhoffm"},"datePublished":"2017-11-14T23:35:47.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/9786/matplotlib/issues/9786"}