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.
