Thanks for the recent pull requests Steve. You've taken the initiative on this, so perhaps you could let me know which areas I can best assist with, without stepping on what you're currently doing.
On Friday, June 2, 2017 at 2:24:19 AM UTC+9, Steve Johnson wrote: > > Could you rephrase your first paragraph? I'm having a little trouble > understanding what you mean. Why do you have to worry about older versions > when working on the site for the latest version? > > > On Thu, Jun 1, 2017, at 02:17 AM, Rob van der Most wrote: > > Indeed doing it all in Sphinx should be easy. The only slightly tricky > thing is linking to older versions and then not generating the whole site > for older versions, but that could just be a flag in the release > maintenance branch. > > The current site is pretty limited, see: > https://bitbucket.org/pyglet/pyglet/wiki/Home > > Rob > > On 1 June 2017 at 05:26, Steve Johnson <[email protected] <javascript:>> > wrote: > > > 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] <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] <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] <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.
