Hi Everyone! The new SymPy Documentation Style Guide is nearly ready to be merged with documentation. If you wanted to share any feedback please comment on the pull request by Friday: https://github.com/sympy/sympy/pull/17715
Thank you to everyone for all of your great feedback to date! Lauren On Wed, Oct 9, 2019 at 2:49 PM Lauren Glattly <[email protected]> wrote: > 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 > <https://groups.google.com/d/msgid/sympy/8750f949-2fbc-491e-af40-a68feb6f5dbd%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- 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/CANA%2BcPsci%3DFY94O_Kb4hzz%2Bau%3DE1t2tBXM%3DTrZJe4p4aDD8-xA%40mail.gmail.com.
