Hey Steve, No offense taken here! I'm very much in support of improving the maintainability of the documentation, and lowering barriers to contributing. I'd ask Rob, Leif and others to chime in here with their own opinions of course, but I think everyone would agree that improvements are good.
For my part, I'm more than willing to put in the manual work of cleaning up and rewriting docstrings if necessary. I'm not intimately familiar with the documentation, but I know the one concern we have is that the event classes are documented correctly. I'm not sure if this is something that is now able to be handled py Sphinx without patching, but maybe so. What would you say is a good path forward? On Tuesday, May 30, 2017 at 5:46:29 AM UTC+9, Steve Johnson wrote: > > 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.
