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.
