Indeed, this looks very good. Thanks a lot. On 9 June 2017 at 02:03, Richard Jones <[email protected]> wrote:
> Wow, this is fantastic, thanks Steve! > > > On 9 June 2017 at 01:42, Steve Johnson <[email protected]> wrote: > >> In my previous PR I actually changed is_epydoc to be True if it's running >> in Sphinx, and a lot of the stuff under those conditionals is helpful for >> "..autoclass::" and such. So no, it shouldn't be removed yet. But in the >> future, we could potentially remove it if we just move the docs to the rst >> files instead of the Python files. It will just mean the API docs are no >> longer centralized in the Python files alone. >> >> I just updated the docs at steveasleep.com/pyglet-docs, so you can see >> the results and maybe ease your mind about the removal of the autosummary >> stuff. >> >> >> On Thursday, June 8, 2017 at 8:02:31 AM UTC-7, Benjamin Moran wrote: >> >>> Haha, great title. >>> >>> I had a quick skim over your pull request and it all looks good so far. >>> Thanks for all of your effort, especially on #3 and #4 in your pull >>> request. I haven't looked at the actual code changes yet, but I don't see >>> any issues with what you've layed out in #2, #3 and #4. #1 is the biggest >>> change of course, but as a lot of it was broken, i'm inclined to say lets >>> go with it. >>> (By the way, am I right in assuming that we can safely purge all of the >>> "is_epydoc:" stuff from the codebase?) >>> >>> I'll give your request a read over, and then once we get it merged I'll >>> work on refactoring your guide. >>> >>> -Ben >>> >>> >>> >>> On Thursday, June 8, 2017 at 3:18:38 PM UTC+9, Steve Johnson wrote: >>> >>>> I went a bit overboard. https://bitbucket.o >>>> rg/pyglet/pyglet/pull-requests/67/documentation-ii-electric- >>>> boogaloo/diff >>>> >>>> After doing all that I'm going to take a break for a couple weeks >>>> (after addressing review comments of course, if there are any) so there >>>> should be no worry about you stepping on my toes! >>>> >>>> If you're up for it, I would love it if you could port my tutorial over >>>> next. Not only would it become more of a group effort, but I would also not >>>> have to re-read all my bad old writing... >>>> >>>> On Wednesday, June 7, 2017 at 7:25:59 PM UTC-7, Benjamin Moran wrote: >>>> >>>>> 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/pyg >>>>>> let/pyglet/wiki/Home >>>>>> >>>>>> Rob >>>>>> >>>>>> On 1 June 2017 at 05:26, Steve Johnson <[email protected]> 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/8288ac67654b >>>>>> d5dbfdd47166c00d3728c6826c5d/doc/modules/app.txt?at=doc-impr >>>>>> ovements&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-had >>>>>> oopy-runners.html#option-check_input_paths >>>>>> [2] http://mrjob.readthedocs.io/en/latest/guides/configs-ref >>>>>> erence.html >>>>>> [3] https://github.com/Yelp/mrjob/blob/master/docs/options_e >>>>>> xtension.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.c >>>>>> om/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. >>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> <div st >>>>>> >>>>>> -- >> 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.
