GSOD Project Discussuion

[nemesis]

I want to do a GSOD project and I would like to discuss it with the mentors before submitting the proposal.

My goal would be to update docstrings throughout sympy to adhere to Lauren Glatty's guide style guide that was developed previously.

This would include adding docstrings and doctests where are missing throughout sympy documentation.

[Aaron Meurer]

Hi.

Sorry for not replying sooner to this. I think this is a good project.
However, I would suggest restricting the project to only fixing the
existing documentation. This is in itself quite a bit of work,
considering that SymPy has a lot of documentation and most of it
hasn't been updated to match the style guide. Also writing new
documentation will be a much harder task, as it generally requires
domain knowledge of the specific functions.

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/15687c68-30fa-4170-a6ca-c1323b309f01o%40googlegroups.com.

[Soumi7]

I think that is right, most docstrings across sympy do not follow the style guide developed previously. It is a lot of work and I shall limit my project to it. 

Right now, the changes have been applied to the specials submodule only, The aim of this project will be to edit all docstrings throughout sympy to adhere to the style guide developed by Lauren Glattly.

I have previously worked as a technical writer for organizations like Data Driven Investor, Analytics Vidhya,etc. I think this will be a good project for me.

[Soumi7]

I submitted a PR editing some of the docstrings of the specials submodule to adhere to the style guide which was merged.

Should I open issues and start submitting PRs for the other submodules already or should I do that later as a part of the project itself?

 

[Nikhil Maan]

You can submit PRs and open issues whenever you feel comfortable and are free to contribute. Contributions are always welcome with or without the program.

Also, since you're planning to update the docstrings throughout the project to match the style guide, I think we should have a discussion regarding the docstring sections.
Here are some of the previous discussions for reference: https://groups.google.com/forum/#!topic/sympy/bXwxVEkbuLk and https://github.com/sympy/sympy/pull/17715

Regards,
Nikhil Maan

[S.Y. Lee]

It depends on what kind of topics you are comfortable to work with, but I'm sure that even the core docs are too outdated

https://docs.sympy.org/latest/modules/core.html

and doesn't follow the style guide.

[Aaron Meurer]

Regarding opening issues, I noticed that we don't have an issue
tracking the documentation style guide, so I opened
https://github.com/sympy/sympy/issues/19591. This issue will track all
the modules that need to be updated to the style guide, so that we
don't have multiple issues. For those with access, feel free to edit
that issue to include a checklist of all the modules that need to be
updated.

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/446577d9-0f71-456f-81b0-5e535310cdd6o%40googlegroups.com.

[Soumi7]

Before implementing the new style guide, we should finalize the location of parameters list and add the returns section as you suggested.

Here is a proposed view. 

[Soumi7]

As suggested by asmeurer, editing all docstrings throughtout sympy to adhere to the already existing style guide will be a big task, so I am not sure if I should add new sections. 

I can change the location of the Parameters list to appear before examples as I think that will be beneficial.

[Soumi7]

Yes, I looked at the core docs too. They are outdated and the docstrings have to be edited to adhere to the latest documentation style guide. Will work on this.

[Soumi7]

Next I want to get started with implementing the style guide to functions.elementary. 

However, Before that I think it is important to decide the order of the subheaders. 

@nikhil maan For the time being there can be two approaches for me:

1. Proceed with the latest existing guide but change the location of the Parameters section only.

2. Add a returns section to the style guide and then proceed

[Soumi7]

As discussed,I shall work on implementing the existing style guide throughout sympy for the GSOD project.

[Soumi7]

This shall be limited to fixing the existing documentation.

[Soumi7]

Is there a way to know which modules of sympy are most widely used? 

Then I can decide an order in which to update the modules and submodules for the latest docstring style guide.

[Aaron Meurer]

We did a survey a few years ago that can offer some insights on this.
Also it may be better to start with modules that are easier to update,
even if they are less used.

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/0ca95802-fd31-43b4-83e5-9e0837805bd7n%40googlegroups.com.

[Nikhil Maan]

Hi Soumi,

Have you decided on which modules you would like to update as part of your project?
The application deadline is in 3 days. So, make sure to complete your proposal before that.
Also, it would be great if you can post a link to your proposal here so we can discuss that too before the deadline.

Regards,

Nikhil Maan

On Thursday, July 2, 2020 at 12:50:46 AM UTC+5:30, Aaron Meurer wrote:

We did a survey a few years ago that can offer some insights on this.
Also it may be better to start with modules that are easier to update,
even if they are less used.

Aaron Meurer

On Sun, Jun 28, 2020 at 8:24 AM Soumi7 <soumiba...@gmail.com> wrote:
>
> Is there a way to know which modules of sympy are most widely used?
>
> Then I can decide an order in which to update the modules and submodules for the latest docstring style guide.
>
> On Wednesday, June 24, 2020 at 4:34:15 PM UTC+5:30 Soumi7 wrote:
>>
>> This shall be limited to fixing the existing documentation.
>>
>> On Wednesday, June 24, 2020 at 4:33:10 PM UTC+5:30 Soumi7 wrote:
>>>
>>> As discussed,I shall work on implementing the existing style guide throughout sympy for the GSOD project.
>>>
>>> On Friday, June 19, 2020 at 11:20:44 AM UTC+5:30 Soumi7 wrote:
>>>>>
>>>>> Next I want to get started with implementing the style guide to functions.elementary.
>>>>
>>>>
>>>> However, Before that I think it is important to decide the order of the subheaders.
>>>>
>>>> @nikhil maan For the time being there can be two approaches for me:
>>>>
>>>> 1. Proceed with the latest existing guide but change the location of the Parameters section only.
>>>>
>>>> 2. Add a returns section to the style guide and then proceed
>
> --
> 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 sy...@googlegroups.com.

[Soumi7]

Yes I have. However, feel free to make comments or suggestions on the proposal.

I am ready to submit my proposal.

Here is the link : https://docs.google.com/document/d/15e6BzUPdqG37QQFgyUVTrwEBfx6FWQdWFzzIe7upgq0/edit?usp=sharing

Thanks

[Aaron Meurer]

If I am reading them correctly, the GSoD instructions specify that the
project description should be included entirely in the Google Form
https://developers.google.com/season-of-docs/docs/tech-writer-application-hints

> Don't supply a link to your project description. The description should include all the definitive details of your project. The open source organization must be able to make a selection based on the content of the application form rather than on content held elsewhere. If you need to link to other content that supplements the description, that's OK, but be aware that only the content of the application form is used for project selection.

So you should make sure that your proposal can be inserted into the Google form.

Aaron Meurer

> 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/2d5ac1ee-5f14-49ed-8ee8-c4a0e9b284e3n%40googlegroups.com.

[Soumi7]

Yes I have already submitted my proposal in the google form. Whatever I have written in the doc, I have added to project description section in the form(the copied text). 

I have already submitted the form. I can keep editing the form till the application deadline, thats what I am doing.

[Soumi7]

My project got accepted. Looking forward to it!