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.
