Sounds great, I'm in! BTW, I'm already all in on Python 3, but it looks like the current docs are omitting all methods on all classes and I suspect Python 3 is the reason. I'm not sure I'll be able to track that one down. I opened a ticket for it yesterday on BitBucket.
On Tue, May 30, 2017, at 05:16 AM, Rob van der Most wrote: > We could also add a branch on bitbucket? We can then give you write > access to the official repository and I can set up a RTD job for > generating the new documentation.> > It would be excellent if we can get rid of the sphinx patches. > > One word of warning: you need to use Python 3 to generate the > documentation due to https://github.com/sphinx-doc/sphinx/issues/1641> > Rob > > On 30 May 2017 at 09:05, Benjamin Moran <[email protected]> wrote:>> > Sounds good to me. Let me know when you have the fork ready, and we >> can start hacking away on it.>> Having a public site up will be a great for >> getting feedback on the >> direction.>> >> Speaking of docstrings, what are your thoughts on the current >> docstring format?>> >> >> >> >> On Tuesday, May 30, 2017 at 1:58:51 PM UTC+9, Steve Johnson wrote: >>> I forgot to add number zero: make sure all the existing modules have >>> complete docstrings! I'd rather focus on that before anything else.>>> >>> But yeah, I'm interested in doing a lot or most of this. Remember >>> that there's no risk of breaking the existing docs, because the API >>> rst files are already valid.>>> >>> Your proposal is a good one. Let's do that. I can use my fork and >>> just host the static site on GitHub Pages.>>> >>> On Monday, May 29, 2017 at 9:02:53 PM UTC-7, Benjamin Moran wrote: >>>> Sounds perfectly reasonable to me (espeically #4), but I admit I'm >>>> not as familiar with documentation as I should be.>>>> It would be ideal >>>> to start hacking on this without breaking the >>>> existing docs, which are being automatically built by Read the >>>> Docs. By the way I believe Rob has set this up, and has ownership >>>> of that Read the Docs account. (It was set up before I started >>>> contributing).>>>> >>>> There are Sphinx patches included with pyglet to handle the event >>>> stuff, but we probably should check if they're even needed anymore >>>> with recent versions.>>>> >>>> If you are feeling up to spearheading this effort, I'm happy to >>>> work with you on it. Maybe we can work off of a fork to start, and >>>> set up a temporary online docs page. Does that make sense, or what >>>> would be easiest?>>>> >>>> >>>> On Tuesday, May 30, 2017 at 12:26:13 PM UTC+9, Steve Johnson wrote:>>>>> >>>> In my ideal world, the pyglet project would take the following >>>>> steps:>>>>> >>>>> 1. "Freeze" the current contents of doc/api. All further updates >>>>> will be done by hand.>>>>> 2. Check each page by hand. Make any >>>>> relevant cleanup tweaks. From >>>>> what I can see now, this mostly involves getting rid of bogus >>>>> "Variables" and "Defines" sections that just list random >>>>> imports from `future`.>>>>> 3. When it looks good, delete all the >>>>> doc/api-generating code and >>>>> just make sure API updates are reflected in the docs.>>>>> 4. Go to >>>>> town updating each individual page to be as good as it >>>>> can possibly be! Module pages can become more topic-oriented >>>>> where appropriate, rather than having a hard divide between >>>>> "programming guide" and "API reference." Django is a good >>>>> example of this, although they take it too far for my taste. >>>>> Some of the pyglet modules already do a good job.>>>>> >>>>> The current system is actually really nice in that you've already >>>>> got valid rst, you just need to stop doing the intermediate step! >>>>> By removing the rst-generating step, you just end up with a >>>>> working set of rst files.>>>>> >>>>> It might sound like you'll lose time manually tweaking the rst >>>>> files over time, but in practice it's adding/removing an >>>>> `..autoclass::` here and there, and you more than make up for it >>>>> in reduced time spent fighting with the tools. (Spread out over >>>>> newbie contributors like me, of course!)>>>>> >>>>> Speaking of event documentation specifically, it's definitely very >>>>> important! But it's exactly the kind of thing you can handle with >>>>> a Sphinx extension rather than a preprocessing step, which I >>>>> believe is what is already happening. You might not need to make >>>>> any changes at all. But if you do, I have a lot of experience >>>>> writing Sphinx extensions from scratch and can probably help out.>>>>> >>>>> What that looks like in practice is that you'll have a class >>>>> docstring with a directive like this:>>>>> >>>>> .. pyglet:event:: on_eos >>>>> >>>>> Fires when the current source ends. >>>>> >>>>> You can make the HTML look pretty much however you want. The mrjob >>>>> project uses it to define[1] and collect[2] command line options. >>>>> I wrote the extension[3] to make it trivial for documentation >>>>> authors. (I disliked the experience so much I wrote a competing >>>>> documentation system[4], but I wouldn't try to convince you to >>>>> switch.)>>>>> >>>>> [1] >>>>> http://mrjob.readthedocs.io/en/latest/guides/configs-hadoopy-runners.html#option-check_input_paths>>>>> >>>>> [2] >>>>> http://mrjob.readthedocs.io/en/latest/guides/configs-reference.html>>>>> >>>>> [3] >>>>> https://github.com/Yelp/mrjob/blob/master/docs/options_extension.py>>>>> >>>>> [4] http://steveasleep.com/computerwords/ >>>>> >>>>> On Monday, May 29, 2017 at 8:04:57 PM UTC-7, Benjamin Moran wrote:>>>>>> >>>>> 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. > > > -- > 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. -- 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.
