Pyglet documentation

[Benjamin Moran]

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

[Steve]

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. :-)

[Rob van der Most]

That would be great! I would also love to hear some additional feedback about the current weaknesses in the documentation. Then we can also improve.

Rob

--
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 pyglet-users+unsubscribe@googlegroups.com.
To post to this group, send email to pyglet...@googlegroups.com.
Visit this group at https://groups.google.com/group/pyglet-users.
For more options, visit https://groups.google.com/d/optout.

[Benjamin Moran]

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?

[Steve]

It's in Markdown. I'm sure something like Pandoc could convert it with good fidelity. It also has a sample code repo.

[Benjamin Moran]

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.

[Steve Johnson]

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.

[Steve Johnson]

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. :-)

[Benjamin Moran]

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? 

[Steve Johnson]

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/

[Benjamin Moran]

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?

[Steve Johnson]

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.

[Benjamin Moran]

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?

[Rob van der Most]

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

--

[Benjamin Moran]

That would be even better.

I take it you're liking Steve's suggestions as well :)

To unsubscribe from this group and stop receiving emails from it, send an email to pyglet-users...@googlegroups.com.

[Steve Johnson]

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.

To unsubscribe from this group and stop receiving emails from it, send an email to pyglet-users...@googlegroups.com.

[Steve Johnson]

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.

[Benjamin Moran]

I personally have no issue with that.

To unsubscribe from this group and stop receiving emails from it, send an email to pyglet-users...@googlegroups.com.

To post to this group, send email to pyglet...@googlegroups.com.

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 pyglet-users...@googlegroups.com.

[Rob van der Most]

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

To unsubscribe from this group and stop receiving emails from it, send an email to pyglet-users+unsubscribe@googlegroups.com.

[Steve Johnson]

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.

[Steve Johnson]

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

[Benjamin Moran]

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.

[Steve Johnson]

What's your wish list for a proper site? Doing it all in Sphinx isn't hard.

[Rob van der Most]

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

To unsubscribe from this group and stop receiving emails from it, send an email to pyglet-users+unsubscribe@googlegroups.com.

To post to this group, send email to pyglet...@googlegroups.com.

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 pyglet-users+unsubscribe@googlegroups.com.

[Steve Johnson]

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?

[Benjamin Moran]

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.

[Steve Johnson]

I went a bit overboard. https://bitbucket.org/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...

[Benjamin Moran]

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

[Steve Johnson]

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.

--

<div st

[Richard Jones]

Wow, this is fantastic, thanks Steve!

To unsubscribe from this group and stop receiving emails from it, send an email to pyglet-users+unsubscribe@googlegroups.com.

[Rob van der Most]

Indeed, this looks very good. Thanks a lot.

[Benjamin Moran]

I started pitching in a little by going through the programming guide and making some small changes for clarity.

After a first pass over, I'll start adapting your game example. Right now, the "Writing a Pyglet Application" ends with "Where to next?". I'm thinking that we need a new top level section (perhaps at the bottom), titled something like "A more in-depth example application", or "Example Application #1" (if we plan to add more). The "Where to next" can point to that.

I'm also thinking that it's long past time to remove "Appendix: Migrating to pyglet 1.1". There is a lot of useful information in there, however, so we should also improve the relevant sections with this info if it makes sense.

[Max Greason]

Hello! I'm a new user to Pyglet - I was looking for a graphics-and-other-stuff library to get started on making applications with more than a CLI, and when looking at what options were out there, Pyglet seemed like an attractive option. (I kept seeing opinions of the form "Pyglet would be a better API than Pygame, but I can't recommend it because the community is dead, the documentation is a bit crap, and it's not maintained." Since Pyglet seems to be maintained again, and I was willing to try looking through source if the docs were insufficient, I thought I'd take a crack.)

So from the perspective of a new user, I can absolutely vouch that the "Writing a Pyglet Application" section really, really, needs something like an "Example application" section. Right now, it simply ends with "The examples presented in this chapter should have given you enough information to get started writing simple arcade and point-and-click-based games", which - no. Given what information is actually provided by the examples, not only is that deeply intimidating, it's borderline *insulting*. "Here's "Hello, World." Here's a way to draw a static image. Here's a way to play an .mp3 file. Here's a way to do something when someone presses a key. If you can't figure out how to make Space Invaders from that, kindly fuck off." It sort of looks like enough, but the moment you try to actually do something with it, you start running into questions like "Where do I put my game logic? Surely not all inside on_key_press?" and "Once I've drawn an object, how do I make it move?" 

Judging from the comments I saw elsewhere where people were asking about Pyglet vs Pygame, this experience seems to be typical.

(And there's no mention of sprites at all, which as far as I can tell are how you're actually *supposed* to draw images for game stuff judging by the rest of the docs)

An example arcade-type game would be *extremely* valuable. The 2009 tutorial that Steve Johnson posted up there for a simple Asteroids game would be basically perfect, if updated to 1.3. 

[Benjamin Moran]

Thanks for your comments, Max.

I've asked around on different forums, and the feedback I've seen has been similar to yours.

I'm very grateful to Steve for stepping up to the plate here and getting things moving. I've been busy this last week, but im going through the programming guide a little each day and making small changes and fixes. When I'm done with that, I will start reworking Steve's guide into a new section.  I think I'm also going to drop the "upgrading from 1.1" section, since that's really out of date at this point. There are maybe some good points in there, however, so if it makes sense these can get added to the other sections.

I'll let you guys know when I've pushed those docs, and hopefull we can get a few eyes on it.

[Paul Craven]

Here's an example of a with a lot of example code:

http://arcade.academy/examples/index.html

Arcade it built on Pyglet, but designed to be easier for new programmers.

[Benjamin Moran]

Hey Paul,

Good to see you here. I've been thinking that we can add a section in the documentation for "Projects using pyglet". If it's OK with you, Arcade seems like a good choice for that.  Something like:

Arcade:  <Short description of the project. A few lines. >
http://www.link-to-project-page.com

Project B: <Short description of the project. A few lines.>
http://www.some-other-link.com

[Paul Craven]

That would be a good idea. I'll update my main description to point to Pyglet as right now it is just in the development notes.

[Benjamin Moran]

I've just about finished a quick pass over all of the programming guide, and I'm at the point where I'm ready to start "porting" over your guide, Steve.
I've been really busy with real life things, but I'm going to try finishing this up soon.

If anyone wants to have a look at the current state,  the link is:   http://pyglet.readthedocs.io/en/latest
It seems to take a long time for the new changes to reflect, so give it a few hours or so.

I think there is still a lot to be done with improving the content, so this is by no means final. Since Steve got the ball rolling on the technical parts of the documentation, I think we can try harder to get the content up to a nicer quality as well.

[Benjamin Moran]

I've finished "porting" your guide, Steve. I also made a lot of little tweaks throughout the programming guide for clarity. We could certainly do a lot of improvement with regards to raw content, but I think it's in a state where we can take a break and get the next pyglet version out. In the future we can certainly improve it more!

One issue is that ReadTheDocs is consistantly failing to build the documentation. In fact, it's been failing builds forever now. The strange thing is that occasionally the documentation does get updated, despite the failed builds. I am able to build the documentation locally, but I'm at a loss for how to fix things at ReadTheDocs. If anyone with more knowledge could have a look, that would be awesome!

http://readthedocs.org/projects/pyglet/builds/

-Ben

[Steve Johnson]

From the error log, it looks like pdftex is running during the html build and finds something it doesn't like. See if you can get it to just not try to build a pdf?

[Benjamin Moran]

I haven't been able to find any way to do that on Read the Docs, but maybe I'm missing it somewhere. Removing the latex options from the makefile don't seem to have any effect either (but I was just taking a shot in the dark there).

I'm going to play around with it more in my personal fork.

[theab...@gmail.com]

Hi!

I've been lurking around on the mailing list for a while, waiting to

get involved with pyglet.

> Removing the latex options from the makefile don't seem to have any

> effect either (but I was just taking a shot in the dark there).

Have you tried keeping the latex options, but making sure that they

don't do anything? This way sphinx finds the options it needs, but

those options don't actually try to do anything. Commenting out the

non-echo lines in the `latex` and `latexpdf` options seems to make

sphinx happy on my machine.

    doc hg:(default) ✗ make latex

    Build finished; the LaTeX files are in _build/latex.

    Run `make' in that directory to run these through (pdf)latex (use `make latexpdf' here to do that automatically).

    

    doc hg:(default) ✗ make latexpdf

    Running LaTeX files through pdflatex...

    pdflatex finished; the PDF files are in _build/latex.

I looked through the build log and could identify two reasons for the

failing build.

    ~ grep -e "^\!" pyglet_error_log.txt | sort | uniq

    !  ==> Fatal error occurred, no output PDF file produced!

    ! LaTeX Error: Unknown graphics extension: .svg.

    ! Misplaced \cr.

    ! Missing \cr inserted.

    ! Missing \endgroup inserted.

    ! Missing } inserted.

* The Pyglet documentation uses SVG images and they aren't supported

  by pdflatex. I wrote a quick script that uses inkscape to convert

  all SVG images in a folder to PNG <https://gist.github.com/abhikpal/824aee001ee3dcc35cba65146145b860>

  The files that use svg images are:

    doc hg:(default) grep -e "fig.*svg" -r ./

    

    ./programming_guide/context.txt:.. figure:: img/context_flow.svg

    ./programming_guide/context.txt:.. figure:: img/screens.svg

    ./programming_guide/mouse.txt:.. figure:: img/mouse_coordinates.svg

    ./programming_guide/text.txt:.. figure:: img/font_metrics.svg

    ./programming_guide/image.txt:.. figure:: img/abstract_image.svg

    ./programming_guide/image.txt:.. figure:: img/image_sequence.svg

    ./programming_guide/image.txt:.. figure:: img/image_grid.svg

    ./programming_guide/image.txt:.. figure:: img/buffer_image.svg

    ./programming_guide/windowing.txt:.. figure:: img/window_location.svg

    doc hg:(default) ✗ grep -e "ima.*\:.*svg" -rw ./ 

    ./programming_guide/text.txt:    .. image:: img/text_classes.svg

    Binary file ./_build/doctrees/programming_guide/text.doctree matches

    Binary file ./_build/doctrees/internal/wraptypes.doctree matches

    ./internal/wraptypes.txt:.. image: wraptypes-class.svg

* The "Misplaces \cr", etc errors are related to tables in the pyglet

  docs. Still looking for a way around this.

I'm still figuring out mercurial, so it will take me a while before I

actually start making pull requests :( can someone try these?

—

Abhik

[Benjamin Moran]

Hi Abhik,

Thanks a lot for your suggestions. I've been testing this in my own fork, so that I don't clog up the main repository with test commits.

I was thinking about the svg errors. It would be nice to keep them as svg, but I suppose that converting them is fine if it will help get past the failure points. (Thanks for the script!)

I'll implement your suggestions in my fork, and let you know how it goes. I have Read The Docs set up to build my fork as well. Its strange, because even though the builds fail, the new docs seem to magically appear on RTD after a day or so.

Mercurial does take a bit of getting used to. Let us know if you have questions. Maybe we can update the docs to add a few pointers on how to get started.

-Ben

[Abhik Pal]

> Mercurial does take a bit of getting used to. Let us know if you

> have questions. Maybe we can update the docs to add a few pointers

> on how to get started.

I've worked through a tutorial or two, but it would be nice to have

some more pyglet-specific details (+examples?) in the Contribute page

in the wiki. I would be more than happy to take this up after I figure

things out for myself.

—

Abhik

[Benjamin Moran]

One thing that's not ideal, is that we have some duplicated things between the wiki and the docs. The "contributing" section is basically the same in both places. And, as you know, the home page is currently pointing towards the wiki on Bitbucket.

I agree that it would be useful to have some more specific details about how to contribute, but I don't think we want to put a bunch of Bitbucket specific things in the proper documentation.

Perhaps the Bitbucket wiki can contain these specific details where they relate to forking/pull requests on Bitbucket.
The documentation, in comparison, can cover more high-level overview of the development process. For example, the fact that we do most development in the default branch, and use specific branches for releases, etc.

-Ben