Just realized my first sentence might sound a bit ungrateful, but I promise that is not the case. I'm just trying to make a point and express my opinions about best practices. :-)
On Monday, May 29, 2017 at 1:45:47 PM UTC-7, Steve Johnson wrote: > > I just spent some time improving some of the docs, and I must stay, I am > moderately horrified at the autogenerated rst files. Why not just write > them by hand like everybody else and use autoclass/:members:? It's not at > all onerous to keep them up to date. > > As someone who writes a LOT of Python docs, largely for fun ( > https://mrjob.readthedocs.io, https://pillow.readthedocs.io, > http://steveasleep.com/clubsandwich, ...) this honestly makes me hesitant > to put a lot of effort into contributing, because it's an unusual and > limiting way to do things. > > The epydoc layout of one class per page with a strict structure of > [inheritance, methods, attributes] is not good for discovery or inline > narrative documentation. And the intermediate api/*.txt-generating layer is > both a barrier to contribution, and limits the flexibility of the > individual pages. > > So above and beyond fixing the many, many missing docstrings, my number > one request (which I would gladly do myself!) is that the API docs be > switched over a more conventional Sphinx setup. > > On Sunday, May 28, 2017 at 11:54:05 PM UTC-7, Benjamin Moran wrote: >> >> Thanks Steve, >> >> I found the markdown files on your github. They'll probably need a few >> paragraphs adjusted to fit the rest of the documentation, but it's a good >> addition and certainly better than what we have now. >> >> I was also looking through some old conversations on the mailing list, >> and it looks like we can remove a lot of old epydoc cruft from the codebase. >> >> >> >> >> On Monday, May 22, 2017 at 4:27:09 AM UTC+9, Steve Johnson wrote: >>> >>> It's in Markdown. I'm sure something like Pandoc could convert it with >>> good fidelity. It also has a sample code repo. >>> >>> On Monday, May 15, 2017 at 6:42:59 PM UTC-7, Benjamin Moran wrote: >>>> >>>> Thanks for the offer Steve. I think we talked about this in the past >>>> but didn't follow up. >>>> It would be a good first step to dump your site into rst, and then edit >>>> it from there. >>>> The raw site wouldn't happen to be in rst already, would it? >>>> >>>> On Saturday, May 13, 2017 at 2:59:39 AM UTC+9, Steve wrote: >>>>> >>>>> I am interested in helping out with this. I've been a pyglet user >>>>> since 2008 and always thought the docs were pretty bad in comparison to >>>>> projects of similar size and maturity. My own best documentation work is >>>>> this: http://mrjob.readthedocs.io/en/latest/ >>>>> >>>>> Specifically, the current pyglet docs do not actually document all the >>>>> APIs! You have to read the source code and see the old epydoc docstrings, >>>>> or at least this was true as of a few weeks ago. The media.Player class >>>>> in >>>>> particular has this problem. >>>>> >>>>> I am the author of this out-of-date tutorial: >>>>> http://steveasleep.com/pyglettutorial.html >>>>> Now that pyglet is being maintained again, I would love to just >>>>> contribute the tutorial to the actual docs and redirect my page. And when >>>>> I >>>>> get some time, I will help fill out the rest of the pyglet docs. But I >>>>> can >>>>> make no promises about when that will be. :-) >>>>> >>>>> On Thursday, May 11, 2017 at 10:34:30 PM UTC-7, Benjamin Moran wrote: >>>>>> >>>>>> Hi everyone, >>>>>> >>>>>> I'm looking for ideas for how the pyglet documentation can be >>>>>> improved, both in terms of missing things or sections that should be >>>>>> added. >>>>>> I've personally always found the technical aspects of the >>>>>> documentation to be quite good, but I hear often that the documentation >>>>>> as >>>>>> a whole is not so clear for new users. >>>>>> In particular, the "writing a pyglet application" section is perhaps >>>>>> a bit to light. >>>>>> >>>>>> Better than suggestions would be if anyone wants to get involved with >>>>>> writing something new or improving existing sections. Please let me know >>>>>> if >>>>>> you're interested in getting involved. Even if you're not comfortable >>>>>> with >>>>>> making pull requests, I'd be more than happy to work directly with you >>>>>> to >>>>>> handle contributions. >>>>>> >>>>>> -Ben >>>>>> >>>>> -- You received this message because you are subscribed to the Google Groups "pyglet-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/pyglet-users. For more options, visit https://groups.google.com/d/optout.
