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.
