I also think that a new repo is the way to go. We don't want to have more (cognitive) load in the documentation.
On Monday, October 12, 2020 at 6:49:02 PM UTC-5 Oscar wrote: > I agree that a separate repo for SymPEPs is best. > > Once 1.7 is released I can try to draft SymPEP 1 soon for discussion > here to bootstrap the process. > > Oscar > > On Tue, 13 Oct 2020 at 00:22, Jonathan Gutow <gu...@uwosh.edu> wrote: > > > > +1 for a separate repo. > > > > I think that initially the default format for SymPEPs should be markdown > > as it renders well in github. Markdown has some serious limitations, so > > their may be reasons to change this later. > > > > Regards, > > > > Jonathan > > > > On 10/12/20 5:06 PM, Aaron Meurer wrote: > > > CAUTION: This email originated from outside of the organization. Do > not click links or open attachments unless you recognize the sender and > know the content is safe. > > > > > > > > > I'd like to restart discussion on SymPEPs. > > > > > > Here are the documents outlining the processes for PEPs, MEPs > > > (Matplotlib Enhancement Proposals), and NEPs (NumPy Enhancement > > > Proposals) > > > > > > https://www.python.org/dev/peps/pep-0001/ > > > https://matplotlib.org/3.1.1/devel/MEP/template.html > > > https://numpy.org/neps/nep-0000.html > > > > > > The MEP and NEP templates are both very similar to PEPs. > > > > > > So I think we should start with SymPEP 1, which would be the outline > > > of the SymPEP process. The first meta question that needs to be > > > answered, though, is where should SymPEPs live, and where should the > > > discussions on them take place? A natural place would be the wiki, but > > > I actually think the wiki isn't the best place. The wiki doesn't have > > > any discussion features, and it also doesn't have any way to do pull > > > requests. Also the wiki allows anyone to edit it without permission, > > > which might not be what we want for SymPEPs. > > > > > > So I would suggest either including them in the main SymPy repo, or > > > creating a new SymPEPs repo for them. Any preference on which would be > > > better? I think I would prefer a separate repo, unless we want to have > > > the rendered documents included in the SymPy documentation, in which > > > case that will be easier if they are in the SymPy repo. In either > > > case, I would suggest for the discussions for any SymPEP to take place > > > on issues or pull requests on the respective repo. > > > > > > Once we decide this, we can start with an actual start for SymPEP 1 > > > and the discussion of what it should look like. > > > > > > Aaron Meurer > > > > > > On Thu, Aug 6, 2020 at 2:08 PM Aaron Meurer <asme...@gmail.com> wrote: > > >> I think the documentation stuff is a bit off topic here. We can > > >> improve documentation and have SymPEPs. In fact, if improving > > >> documentation requires a large concerted effort, that could itself be > > >> a SymPEP. However, I will note that on this front: > > >> > > >> - We are participating in Google Season of Docs (GSoD, not to be > > >> confused with GSoC), which is a program that pays technical writers to > > >> work on open source documentation. The GSoD results will be announced > > >> in a couple of weeks, so watch this space. > > >> > > >> - I agree that we should have a concerted effort to improve > > >> documentation. A documentation sprint is one way. Getting funding to > > >> improve things is another. > > >> > > >> - We have a documentation style guide, which was developed as part of > > >> last year's GSoD. However, only a small subset of SymPy actually > > >> conforms to the guide > > >> https://docs.sympy.org/latest/documentation-style-guide.html. > > >> > > >> Aaron Meurer > > >> > > >> On Thu, Aug 6, 2020 at 1:48 PM Nikhil Maan <nikhil...@gmail.com> > wrote: > > >>> > > >>> > > >>> On Thursday, August 6, 2020 at 9:39:43 PM UTC+5:30 > moore...@gmail.com wrote: > > >>>> A nice thing for a GSoD student to do would be to organize a > documentation sprint. > > >>> > > >>> This sounds like a great idea. > > >>> > > >>> I also like the idea of SymPy Enhancement Proposals. Another project > that I think might benefit SymPEPs is Naman Gera's work on adding control > systems to SymPy. It will be a great place for folks who would like to help > with/continue this work in the future to find the motivations and other > details about the decision choices and future plans. > > >>> > > >>> Looking at PEP-1 and seeing a large portion of the discussion in the > thread is regarding what kind of work should have a SymPEP and what they > should include, I think a good starting point for SymPEP-1 will be to > describe what are SymPEPs, why we are planning to add them, what kind of > changes should have a SymPEP, etc. Also, I like the sound of SymEP and > SymPEP. +1 to calling them SymPEP or SymEP instead of SEP. > > >>> > > >>> Regards, > > >>> Nikhil Maan > > >>> > > >>>> Jason > > >>>> moorepants.info > > >>>> +01 530-601-9791 <(530)%20601-9791> > > >>>> > > >>>> > > >>>> On Thu, Aug 6, 2020 at 5:32 PM Matthew Brett <matthe...@gmail.com> > wrote: > > >>>>> Hi, > > >>>>> > > >>>>> On Thu, Aug 6, 2020 at 4:10 PM David Bailey <da...@dbailey.co.uk> > wrote: > > >>>>>> On 06/08/2020 00:47, Nicolas Guarin wrote: > > >>>>>> > > >>>>>> I agree that this would be good for the project but maybe it > would be a good idea to polish the documentation a bit. Some of the pages > in the wiki are somewhat outdated and they are on the first results in a > web search. > > >>>>>> > > >>>>>> Assuming you are talking about the user level documentation, I > very much agree. > > >>>>>> > > >>>>>> If you look up even the simplest function - e.g. Sin[] - in > Mathematica, you get a simple explanation, some examples showing that it > can be used with real numbers, and that it 'knows' about special arguments > such as Pi/3. > > >>>>>> > > >>>>>> It shows you the power series about zero and a plot of the > function. It also shows some properties of the function such as Sin[x] = > -Sin[-x] etc etc. > > >>>>>> > > >>>>>> It also shows that Sin can be applied to complex arguments, or > even to matrices, and that it can be applied to a high precision floating > point number to deliver a high precision result. > > >>>>>> > > >>>>>> That same level of detail is provided for every function - right > up to complicated functions like MeijerG. Remember that for functions such > as that, the documentation is even more important because there are > different conventions as to the order,sign, etc of the arguments. > > >>>>>> > > >>>>>> This might appear like overkill, but it means that wherever you > start you will realise a Mathemaica function is far more than just a > numerical function. This is also true for SymPy, but the information is > harder to find. It is also easy to cut/paste from the documentation into > your own code. > > >>>>>> > > >>>>>> Of course, the documentation is massively redundant, but I > imagine that the documentation for each function or operation would not be > written from scratch, but pulled from some kind of database of information. > > >>>>>> > > >>>>>> Obviously the SymPy documentation can't jump to the Mathematica > standard overnight, but maybe a student could put together some sort of > framework from which such documentation of the standard maths functions > could be generated, and start the process off - then others could > contribute information that would fit into the same scheme. > > >>>>>> > > >>>>>> I think that such documentation would make SymPy very much more > user-friendly. > > >>>>> Just to say - that the Scipy Documentation Project took Numpy from > > >>>>> fairly woeful documentation, to very good documentation, in a few > > >>>>> months, and with a fairly small budget: > > >>>>> > > >>>>> http://conference.scipy.org/proceedings/SciPy2008/paper_5/ > > >>>>> https://ieeexplore.ieee.org/document/6879046 > > >>>>> > > >>>>> Cheers, > > >>>>> > > >>>>> Matthew > > >>>>> > > >>>>> -- > > >>>>> 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/CAH6Pt5q%3DN_Vb0Z_yM2w8nBKwFFJu8UPBO3_A0c1UeWhAKDBX%3Dg%40mail.gmail.com > . > > >>> -- > > >>> 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/b977b777-52de-43af-81c9-445662ffef9bn%40googlegroups.com > . > > > -- > > > 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/CAKgW%3D6K114c9mbhXLVru4HCVB_M_-4wLdf7pHnz-ceHm97gAiQ%40mail.gmail.com > . > > > > -- > > Dr. Jonathan Gutow > > Chemistry Department > > UW Oshkosh > > web: https://uwosh.edu/facstaff/gutow > > e-mail: gu...@uwosh.edu > > Ph: 920-424-1326 <(920)%20424-1326> > > > > -- > > 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/680e649c-f869-dcb4-f17f-7f5e977a17cd%40uwosh.edu > . > -- 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+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/bd536574-b2c3-4cd8-983f-c91b3dbd4ffcn%40googlegroups.com.
