SymPy Documentation Style Guide first draft feedback

[Lauren Glattly]

Hi Sympyers,

The new SymPy Documentation Style Guide that I'm putting together as part of my Google Season of Docs project with 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? 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 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

[Aaron Meurer]

Thank you for your excellent work on this Lauren.

The feedback from the community on this is very important, so please
take a moment to read it over, and let us know if there are any parts
that are confusing, or parts that you have questions or concerns
about. Once this is merged into our documentation, this will be the
official style guide that all docstrings in SymPy will be expected to
follow, so it's important to have community consensus on this. I
encourage feedback on this both from people who are active
contributors and from people who contribute less often or who haven't
contributed at all yet.

Aaron Meurer

[David Bailey]

On 03/10/2019 19:40, Aaron Meurer wrote:

Thank you for your excellent work on this Lauren.

The feedback from the community on this is very important, so please
take a moment to read it over, and let us know if there are any parts
that are confusing, or parts that you have questions or concerns
about. Once this is merged into our documentation, this will be the
official style guide that all docstrings in SymPy will be expected to
follow, so it's important to have community consensus on this. I
encourage feedback on this both from people who are active
contributors and from people who contribute less often or who haven't
contributed at all yet.

I am not clear if there are actual samples of new documentation available - as opposed to documents about style.

I guess that the real problem is that SymPy would deserve documentation equal in size to some of those Mathematica tomes (produced while it still fitted in one book) which would require a massive effort.

David

[Chris Smith]

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

[Chris Smith]

I'm not sure that it would have to be complete as Mathematica's. I see Mathematica as being more of a computational encyclopedia with a given function having one or more of history, values of interest, syntax, graphs, etc... In SymPy I would expect much less would be needed to show how to use the function after a brief description of what is calculated. Having a reference to a more complete definition would be possible, possibly to Fungrim, wikipedia or Mathamatica.

[Lauren Glattly]

The only samples of documentation/docstrings with this new formatting are the examples in the style guide, but over the next few weeks I'll be working on editing a submodule to reflect these new guidelines as part of the Google Season of Docs project.

[Aaron Meurer]

I agree. The SymPy documentation shouldn't have mathematical reference
material except insomuch as it helps clarify the definition of a
function or illuminate it somehow. This is what the guide says about
mathematical functions:

"The Explanation section may also include some important mathematical
facts about the function. These can alternately be demonstrated in the
Examples section. Mathematical discussions should not be too long, as
users can check the references for more details."

Longer "how to" guides that use SymPy to demonstrate some mathematics
are appropriate for the docs, but these would be separate from the
docstrings (see the video I posted in another thread on this list on
why it's important to keep these separate).

Aaron Meurer

> --
> 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 sympy+un...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/4719ab02-ff10-4f24-8b1a-ccb1bfbad126%40googlegroups.com.

[Lauren Glattly]

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?

[Aaron Meurer]

On Fri, Oct 4, 2019 at 2:37 PM Lauren Glattly <lauren...@gmail.com> 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?

It looks like the wiki doesn't wrap the text if it is in a code block.
If you scroll right on it the text should all be there.

I wouldn't worry about this. If Sphinx does the same thing, we will
need to fix it. But we don't have much control over how the wiki
formats things.

Aaron Meurer

>
> 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 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? 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 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 sympy+un...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/bb721b76-1f64-491e-8011-b4dc12b10b76%40googlegroups.com.

[Aaron Meurer]

Some feedback I got from someone offline:

> Some feedback: also commit messages and code reviews are considered as documentation, see
https://hamatti.org/talks/contemporary-documentation/

I haven't yet watched the talk. I agree commit messages should be
written well, though I don't know if that needs to be part of this
guide (we have some things about that in the developer workflow). I
don't know if I agree that code reviews are documentation.
Conversations often contain information that was relevant at the time
of the discussion, but aren't important for the end result. Sometimes
they even mention things that are no longer correct at all. And unlike
a documentation page, discussions around something like a code review
should be left intact for archival purposes. but documentation should
be something that is always edited and corrected when it becomes out
of date.

Even so, it may be worth mentioning these things (or not, I'll let you decide).

Aaron Meurer

[David Bailey]

On 04/10/2019 21:21, Aaron Meurer wrote:

The SymPy documentation shouldn't have mathematical reference
material except insomuch as it helps clarify the definition of a
function or illuminate it somehow. This is what the guide says about
mathematical functions:

I wasn't thinking of actual mathematical functions so much (although things like specifying where branch cuts are placed would be useful).

I was thinking of Python functions like expand, integrate, diff, , etc. The different possible forms of the arguments need explaining, preferably each with a working example.

It would also be nice to be able to access a list of all the SymPy mathematical functions and a separate list of all the manipulating functions (such as integrate), so that given a job to do, it would be possible to browse for likely sounding names.

David

[Chris Smith]

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

[Jason Moore]

I think that you can make the wiki page RST and it will render, that way you want have to go form google docs > markdown > rst. FYI

Jason

moorepants.info
+01 530-601-9791

--

[Lauren Glattly]

That's a much better example, thanks I'll swap it out!

[Lauren Glattly]

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

[Lauren Glattly]

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

--

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 sympy+un...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/8750f949-2fbc-491e-af40-a68feb6f5dbd%40googlegroups.com.