That would be even better. I take it you're liking Steve's suggestions as well :)
On Tuesday, May 30, 2017 at 9:16:15 PM UTC+9, Rob 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] <javascript:>> > 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] <javascript:>. >> To post to this group, send email to [email protected] >> <javascript:>. >> 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.
