What's your wish list for a proper site? Doing it all in Sphinx isn't hard.
On Wed, May 31, 2017, at 08:21 PM, Benjamin Moran wrote: > Looks good so far. I like the slight changes to the main index - It's > more readable at a quick glance. The fonts look good on my current > monitor. I'm OK with doing the event documentation by hand for now, if > it means simplifying things. We can look into making this more > sophisticated after modernizing it.> > Rob, I like your idea of using RTD for the main site. A proper site > would be nice, but until someone follows through with that, a nice > looking index page on RTD would be great at some point.> > > > > On Thursday, June 1, 2017 at 11:00:58 AM UTC+9, Steve Johnson wrote: >> I went over it a bit more and see what you mean about wanting to call >> out events in particular. In the short term I think we should just do >> it by hand. I went over pyglet.app and pyglet.media that way, I think >> you'll like it: http://steveasleep.com/pyglet-docs/modules/app.html>> >> rst source: >> https://bitbucket.org/irskep/pyglet/src/8288ac67654bd5dbfdd47166c00d3728c6826c5d/doc/modules/app.txt?at=doc-improvements&fileviewer=file-view-default>> >> >> On Wednesday, May 31, 2017 at 9:33:20 AM UTC-7, Steve Johnson wrote:>>> I >> spent last evening replacing everything in doc/api with a fresh >>> set of rst files that I put in doc/modules. I also combed through >>> all the Python files and added proper cross-references where >>> appropriate, and made some manual improvements for usability.>>> >>> Here's how it looks: http://steveasleep.com/pyglet-docs/ >>> >>> There are still a lot of things that can be done, but I believe this >>> is already better than the current site in all the ways that matter. >>> If events aren't documented in a way you're happy with, I would love >>> it if you could give me an example in the old docs where it looks >>> the way you want, and I'll try to match it.>>> >>> On Wednesday, May 31, 2017 at 4:51:47 AM UTC-7, Rob wrote: >>>> I am also open to that. Anything to improve the readability of the >>>> documentation.>>>> >>>> I was also playing with the idea to generate the entire 'website' >>>> using sphinx on RTD. So instead of the wiki pages on bitbucket.>>>> >>>> Rob >>>> >>>> On 31 May 2017 at 06:22, Benjamin Moran <[email protected]> wrote:>>>>> I >>>> personally have no issue with that. >>>>> >>>>> >>>>> On Wednesday, May 31, 2017 at 12:06:35 PM UTC+9, Steve Johnson >>>>> wrote:>>>>>> On a totally separate note, how open are you all to changes >>>>> to >>>>>> the theme? I find the small font on the class and function names >>>>>> hard to read. >>>>>> >>>>>> On Tuesday, May 30, 2017 at 9:25:30 AM UTC-7, Steve Johnson >>>>>> wrote:>>>>>>> >>>>>>> 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. >>>> > > -- > 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.
