Hi Sympyers, Thank you to everyone for all of your great feedback so far! You can now review and share feedback on the new SymPy Documentation Style Guide in the pull request: https://github.com/sympy/sympy/pull/17715
Our deadline to merge the new guide with documentation is November 6, so early reviews are much appreciated. Thank you! Lauren On Tuesday, October 8, 2019 at 4:48:51 PM UTC-4, Lauren Glattly wrote: > > That's a much better example, thanks I'll swap it out! > > On Saturday, October 5, 2019 at 7:37:08 AM UTC-4, Chris Smith wrote: >> >> Maybe a more suitable phrase for quoting would be good since, in this >> case, "other" probably refers to a variable name (as in `__foo__(self, >> other)`) in which case it wouldn't be quoted. Something like "The term >> 'unrestricted necklace,' or 'bracelet,' is used to..." might work better >> for the example. >> >> /c >> >> On Friday, October 4, 2019 at 3:37:29 PM UTC-5, Lauren Glattly wrote: >>> >>> Thank you for the formatting suggestions! I see your point about symbols >>> in the text and like what you did to make the examples stand out more from >>> the rest of the text. I reverted your edits and tried to recreate them in >>> RST (since that's what I'll be using to merge the guide eventually) to see >>> what you did, but the only one I left reverted was the second example under >>> "Spelling and Punctuation" where "other," is meant to be in quotation marks >>> to show American punctuation standards. >>> >>> The only issue I'm seeing with the examples is under "Formatting >>> Preferences" where two of the longer examples are being cut off. Does >>> anyone else see that in their system or know why that would be? >>> >>> On Friday, October 4, 2019 at 8:39:48 AM UTC-4, Chris Smith wrote: >>>> >>>> I made some small edits to the page to try help with meta-formatting. >>>> Please feel free to revert or to use as a suggestion for further edits. >>>> Since you are writing about symbols in the text you might want to use >>>> different formatting there that is consistent with *that* context. >>>> >>>> Also, I tried some formatting to allow examples to stand out as >>>> separate from the text. >>>> >>>> /c >>>> >>>> >>>> On Thursday, October 3, 2019 at 1:27:42 PM UTC-5, Lauren Glattly wrote: >>>>> >>>>> Hi Sympyers, >>>>> >>>>> The new SymPy Documentation Style Guide that I'm putting together as >>>>> part of my Google Season of Docs project with SymPy >>>>> <https://developers.google.com/season-of-docs/docs/participants/project-sympy> >>>>> >>>>> is now available on the SymPy Wiki: >>>>> https://github.com/sympy/sympy/wiki/SymPy-Documentation-Style-Guide >>>>> >>>>> You'll notice that some of the new guidelines in the guide are >>>>> qualified with a Work in Progress note and an issue number. These are >>>>> guidelines that are dependent on resolving certain issues in order for >>>>> the >>>>> guide to be implemented. If you are interested in working on any of these >>>>> issues, the full listing of Google Season of Docs related issues can be >>>>> found here: https://github.com/sympy/sympy/milestone/54 >>>>> >>>>> We would love to have some feedback from the SymPy community on the >>>>> first draft of this new style guide. In particular, we would like to know >>>>> your thoughts on these two issues: >>>>> >>>>> 1. What do you think of the new order for docstring sections >>>>> <https://github.com/sympy/sympy/wiki/SymPy-Documentation-Style-Guide#docstring-sections>? >>>>> >>>>> Do you think it is more helpful for examples to occur earlier in the >>>>> docstring to learn by example, or do you prefer to have all of the >>>>> information about a function, such as parameters, before seeing the >>>>> examples? >>>>> >>>>> 2. How do you think docstrings for classes that are mathematical >>>>> functions >>>>> <https://github.com/sympy/sympy/wiki/SymPy-Documentation-Style-Guide#docstrings-for-classes-that-are-mathematical-functions> >>>>> >>>>> differ from other docstrings? Are there any other details you would like >>>>> to >>>>> see included in this section? >>>>> >>>>> Please feel free to share any other feedback you may have about the >>>>> new guide. Please share any feedback you have by October 21st to allow >>>>> for >>>>> ample time for concerns to be addressed. After October 21st I will be >>>>> finalizing the guide and starting the process to merge it with SymPy's >>>>> documentation. >>>>> >>>>> Thank you in advance for your thoughts and comments! >>>>> Lauren >>>>> >>>> -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/8750f949-2fbc-491e-af40-a68feb6f5dbd%40googlegroups.com.
