Sphinx Documentation

[Richard Thomas]

I'm experimenting with moving the documentation for Pyglet from Epydoc to Sphinx. Epydoc is becoming increasingly difficult to support with newer versions of Python and docutils and its output is starting to look fairly dated too. This is still an experiment; I'm not making a unilateral change to how our documentation is structured. I've added a clone for this effort so that people can offer comments or suggestions.

http://code.google.com/r/chardster-sphinx-docs

Go to the docs directory and type `make html` to build the documentation. You'll need Sphinx (and its dependencies) installed for this to work. If you have problems building the docs please tell me. I've had none which is significantly better than I can say about Epydoc. :-)

Current Status

• Programming guide is being built correctly, not all API links are working but these are not hard to fix. I just finished sorting out the links in the second chapter and the changes needed are only minor.
• API docs are being automatically generated from the docstrings. This is currently done as one document per module but I'm aware that per-class pages of documentation might be desirable. I also want to do something a bit nicer with parameter lists and instance variables.
• I haven't looked at formatting/templating in any great detail at this stage.

[Steve]

I fully support this effort. While we're at it, I may add my pyglet
tutorial (http://www.steveasleep.com/pyglettutorial) to the proper
docs to send PageRank to the right place. I don't get much opportunity
to use pyglet anymore and I don't want it to rot on my site for too
long. I wrote the tutorial in Markdown, but I can convert it to
reStructuredText with pandoc and clean up by hand.

Also, forking things on Google Code is a pain in the butt, which makes
contributing more difficult. What are people's feelings toward moving
to e.g. BitBucket, where the UI is a bit friendlier? Google Code seems
to be a "big project, monolithic contributor" kind of site, but pyglet
seems more and more like a "small project, many contributors" kind of
project. (I suspect this idea will no go over well but there it is.)
I'm comfortable with hg but I literally feel like it would be easier
to email Richard a zip file with my contributions rather than fork and
have him pull.

On Mar 29, 12:53 pm, Richard Thomas <chards...@gmail.com> wrote:
> I'm experimenting with moving the documentation for Pyglet from Epydoc to
> Sphinx. Epydoc is becoming increasingly difficult to support with newer
> versions of Python and docutils and its output is starting to look fairly
> dated too. This is still an experiment; I'm not making a unilateral change
> to how our documentation is structured. I've added a clone for this effort
> so that people can offer comments or suggestions.
>
> http://code.google.com/r/chardster-sphinx-docs
>
> Go to the docs directory and type `make html` to build the documentation.
> You'll need Sphinx (and its dependencies) installed for this to work. If
> you have problems building the docs please tell me. I've had none which is
> significantly better than I can say about Epydoc. :-)
>

> *Current Status*
>
>    - Programming guide is being built correctly, not all API links are

>    working but these are not hard to fix. I just finished sorting out the
>    links in the second chapter and the changes needed are only minor.

>    - API docs are being automatically generated from the docstrings. This

>    is currently done as one document per module but I'm aware that per-class
>    pages of documentation might be desirable. I also want to do something a
>    bit nicer with parameter lists and instance variables.

>    - I haven't looked at formatting/templating in any great detail at this
>    stage.

[Richard Thomas]

On Thursday, 29 March 2012 19:26:13 UTC+1, Steve wrote:

I fully support this effort. While we're at it, I may add my pyglet
tutorial (http://www.steveasleep.com/pyglettutorial) to the proper
docs to send PageRank to the right place. I don't get much opportunity
to use pyglet anymore and I don't want it to rot on my site for too
long. I wrote the tutorial in Markdown, but I can convert it to
reStructuredText with pandoc and clean up by hand.

I was thinking to add a tutorial. The programming guide is quite good but it doesn't have the flow or the continuity that a tutorial would.

Still, I'm most concerned right now with making sure the reference parts of the docs are complete, accurate and easy to use.

 

Also, forking things on Google Code is a pain in the butt, which makes
contributing more difficult. What are people's feelings toward moving
to e.g. BitBucket, where the UI is a bit friendlier? Google Code seems
to be a "big project, monolithic contributor" kind of site, but pyglet
seems more and more like a "small project, many contributors" kind of
project. (I suspect this idea will no go over well but there it is.)
I'm comfortable with hg but I literally feel like it would be easier
to email Richard a zip file with my contributions rather than fork and
have him pull.

It seems that you can't add additional contributers to a clone... That's kind of irritating I assumed that you could.

[Steve]

> It seems that you can't add additional contributers to a clone... That's
> kind of irritating I assumed that you could.

Even if you could, I'd still have to ask/convince you to add me, which
is already like three too many steps.

[Rob McMullen]

> Go to the docs directory and type `make html` to build the documentation.
> You'll need Sphinx (and its dependencies) installed for this to work. If you
> have problems building the docs please tell me.

I think I have a vanilla sphinx (1.1.3) install on python 2.6; but for
some reason it's not finding the local exts without adding:

sys.path.append(os.path.abspath('.'))

to conf.py. The sphinxified docs look great.

Rob

[Nathan]

Do events still get first-class treatment under sphinx? It was nice
how pyglet events were separated in the custom epydoc.

~ Nathan

[Richard Thomas]

Treatment of events will require a small extension. An extension is slightly neater than an entire fork which is what epydoc needed. :)

[Steve]

> Treatment of events will require a small extension. An extension is
> slightly neater than an entire fork which is what epydoc needed. :)

Why? You can just create arbitrary reStructuredText pages.

[Nathan]

On Wed, Apr 11, 2012 at 10:01 AM, Steve <dio...@gmail.com> wrote:
>> Treatment of events will require a small extension. An extension is
>> slightly neater than an entire fork which is what epydoc needed. :)
>
> Why? You can just create arbitrary reStructuredText pages.

I'm sure he doesn't want to hand-craft the API documentation for each
change to the code. He'll want to generate it, which means 'pyglet
events' will need an extension so they can be treated differently than
regular methods.

~ Nathan

[Steve]

Ah, I misunderstood the functionality of the epydoc extension.

Events!
http://pyglet.org/doc/api/pyglet.window.Window-class.html

On Apr 11, 4:01 pm, Nathan <nathan.sto...@gmail.com> wrote:

[Steve]

Any progress here? We should try to get it together for 1.2.

[Steve]

If necessary, we can temporarily write out the events by hand. There aren't that many of them.

[Txema Vicente]

Hola.

I patched sphinx.ext.autosummary to generate event lists automatically
and I did some magic in conf.py, templates and css, too.

See:
http://code.nabla.net/doc/pyglet/api/window/pyglet.window.Window.html#events

Is this what we need?

:) Cheers

[Rui Carmo]

Looks nice.

But, if I may, on the rest of the page you might want to add something like:

dt {background-color: #fffeef; margin-top: 2em;}

so that the class names and method invocation signatures stand out a bit (probably a lighter color - I've just hammered out #fffeef on the webkit inspector as a quick test, and to distinguish it from the .highlighted class). 

The way the colors and spacing are set now, your eye is drawn to the parameters or type boxes first (which, incidentally, are already in bold text) and not to the method names unless you click on the list - which is not necessarily going to be the default behavior :)

A quick question - are there going to be any samples in the docs? I mean something like http://django-tastypie.readthedocs.org/en/latest/api.html#quick-start 

R.

--
You received this message because you are subscribed to the Google Groups "pyglet-users" group.
To post to this group, send email to pyglet...@googlegroups.com.
To unsubscribe from this group, send email to pyglet-users...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pyglet-users?hl=en.

[Richard Jones]

On 17 June 2012 08:02, Txema Vicente <tx...@nabla.net> wrote:
> I patched sphinx.ext.autosummary to generate event lists automatically
> and I did some magic in conf.py, templates and css, too.
>
> See:
> http://code.nabla.net/doc/pyglet/api/window/pyglet.window.Window.html#events
>
> Is this what we need?

Nice work! I'd prefer the style stick to the current website feel if
possible. Otherwise what do I need to do to make this work?


Richard

[Winston Wolff]

Rui-

Thanks for the ideas on the coloring--I think most of the Pyglet docs and website have a clean and readable look and I hope to keep that direction.

> A quick question - are there going to be any samples in the docs? I mean something like http://django-tastypie.readthedocs.org/en/latest/api.html#quick-start

I would certainly like that, I can't imagine anybody opposed. However I think the priority is to get the simplest thing out first. The 1.2 release has been waiting long enough. I'd like to just get 1 bare-bones 1.2 out. Of course if you want to contribute some samples, I'll be sure to incorporate them.

-ww

[Txema Vicente]

You need Sphinx (1.1.3) and this files in pyglet/doc folder from current
repository:
http://code.nabla.net/doc/pyglet/doc.zip

The new "event" object is defined in conf.py, I patched
sphinx.ext.autosummary.generate to:
- Mark methods having ":event:" in __doc__ as events.
- Skip all members starting with "PFN" or "GL"
See doc/ext/autosummary/generate.py

The api folder is where all the API is generated,
the autosummary directives are in the template files.

Install Graphviz if you want the inheritance diagrams.
The executable has to be specified to sphinx-build (see go.bat).
"make html" should work too, without graphs.

El 17/06/2012 5:31, Richard Jones escribi�:

[Rui Carmo]

On Jun 17, 2012, at 24:03 , Winston Wolff wrote:

> Rui-
>
> Thanks for the ideas on the coloring--I think most of the Pyglet docs and website have a clean and readable look and I hope to keep that direction.
>
>> A quick question - are there going to be any samples in the docs? I mean something like http://django-tastypie.readthedocs.org/en/latest/api.html#quick-start
>
> I would certainly like that, I can't imagine anybody opposed. However I think the priority is to get the simplest thing out first. The 1.2 release has been waiting long enough. I'd like to just get 1 bare-bones 1.2 out. Of course if you want to contribute some samples, I'll be sure to incorporate them.

I was thinking along the lines of breaking up one of the smaller samples and adding it in. I'll have a look at the sphinx source and see if I can get along with it (I usually do Markdown or Textile).

R.

[Txema Vicente]

This patch works fine:
http://code.nabla.net/doc/pyglet/pyglet_sphinx_patch.zip

Should we skip pyglet.gl.gl* ?


txema@negro:~$ hg clone https://code.google.com/p/pyglet
destination directory: pyglet
requesting all changes
adding changesets
adding manifests
adding file changes
added 2648 changesets with 8447 changes to 2160 files (+11 heads)
updating working directory
1227 files updated, 0 files merged, 0 files removed, 0 files unresolved
txema@negro:~$ wget http://code.nabla.net/doc/pyglet/pyglet_sphinx_patch.zip

100%[======================================>] 49.989      66,7K/s   en 0,7s

2012-06-18 02:00:27 (66,7 KB/s) - «pyglet_sphinx_patch.zip» guardado [49989/49989]

txema@negro:~$ unzip pyglet_sphinx_patch.zip
Archive:  pyglet_sphinx_patch.zip
  inflating: pyglet/doc/conf.py
   creating: pyglet/doc/ext/
   creating: pyglet/doc/ext/autosummary/
  inflating: pyglet/doc/ext/autosummary/generate.py
  inflating: pyglet/doc/ext/autosummary/__init__.py
 extracting: pyglet/doc/ext/__init__.py
  inflating: pyglet/doc/go.bat
  inflating: pyglet/doc/index.txt
  inflating: pyglet/doc/make.bat
  inflating: pyglet/doc/Makefile
  inflating: pyglet/doc/programming_guide/index.txt
  inflating: pyglet/doc/pyglet_api.txt
   creating: pyglet/doc/_static/
  inflating: pyglet/doc/_static/default.css
  inflating: pyglet/doc/_static/favicon.ico
  inflating: pyglet/doc/_static/logo.png
   creating: pyglet/doc/_templates/
  inflating: pyglet/doc/_templates/base.rst
  inflating: pyglet/doc/_templates/class.rst
  inflating: pyglet/doc/_templates/exception.rst
  inflating: pyglet/doc/_templates/module.rst
  inflating: pyglet/pyglet/__init__.py
txema@negro:~$ cd pyglet/doc
txema@negro:~/pyglet/doc$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.1.3
Generating pyglet 1.2dev Documentation
loading pickled environment... not yet created
[autosummary] generating autosummary for: index.txt, ...
building [html]: targets for 27 source files that are out of date
updating environment: 1034 added, 0 changed, 0 removed
reading sources... [100%] pyglet_api
/home/txema/pyglet/doc/internal/dist.txt:10: ERROR: Unexpected indentation.
/home/txema/pyglet/doc/programming_guide/graphics.txt:32: ERROR: Unknown target name: "opengl programming guide".
/home/txema/pyglet/doc/programming_guide/input.txt:105: WARNING: Inline interpreted text or phrase reference start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] pyglet_api
writing additional files... genindex py-modindex search
copying images... [100%] programming_guide/text_classes.svg
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 3 warnings.

Build finished. The HTML pages are in _build/html.

[Richard Jones]

On 17 June 2012 17:59, Txema Vicente <tx...@nabla.net> wrote:
> You need Sphinx (1.1.3) and this files in pyglet/doc folder from current
> repository:
> http://code.nabla.net/doc/pyglet/doc.zip

Excellent, I've managed to build the docs now even though there's a
considerable WARNING output - which is still an improvement over what
I was able to generate with epydoc :-)

I'm not confident enough with Sphinx to mess with the style stuff -
would it be possible to get a style that more closely matches the
current website style before I commit these changes to the repository?

> The new "event" object is defined in conf.py, I patched
> sphinx.ext.autosummary.generate to:
> - Mark methods having ":event:" in __doc__ as events.
> - Skip all members starting with "PFN" or "GL"
> See doc/ext/autosummary/generate.py

This needs to be recorded somewhere useful, but I honestly don't know
where. Perhaps some "documentation documentation"? :-)

Assuming the sphinx migration goes well (and it appears to be) I'll
look at replacing all the is_epydoc flag checks with is_sphinx for
sanity's sake (well, getting rid of the flag would be saner but
unrealistic at this point.)

I'm a little confused by the samples discussion: what sort of samples
were you thinking of? (there being code samples in the programming
guide and API docs already). Are you thinking of including code from
the examples directory in the documentation? Or are there just gaps in
the samples in the existing docs?


Richard

[Txema Vicente]

Hi.

I noticed that many submodules were missing, now conf.py searchs
recursively for all submodules.
That is huge, and some modules can not be imported to be documented.

So:
skip_modules = {"pyglet.gl": ["agl", "carbon", "cocoa",
"glext_arb", "glext_nv","glx", "glx_info",
"glxext_arb", "glxext_mesa", "glxext_nv",
"lib_agl", "lib_glx", "lib_wgl",
"wgl", "wgl_info", "wglext_arb","wglext_nv",
"win32","xlib"],
"pyglet.window": ["xlib", "carbon","win32", "cocoa"]}


And there are too much members, so far I have trimmed:

def skip_member(member, obj):
module = obj.__name__

if member.startswith("PFN"): return True
if member.startswith("GL"): return True

if module.startswith("pyglet.gl.glext_"): return True
if module.startswith("pyglet.gl.gl_ext_"): return True
if module.startswith("pyglet.gl.glxext_"): return True

if module.startswith("pyglet.graphics"):
if member.startswith("gl"): return True

if module in ["pyglet.gl.gl_info",
"pyglet.gl.glu",
"pyglet.gl.glu_info"]: return True

if module == "pyglet.gl":
if member.startswith("gl"): return True
return False

Comments, changes?

The new patch:
http://code.nabla.net/doc/pyglet/pyglet_sphinx_patch.zip

Should give 5 warnings.

> I'm not confident enough with Sphinx to mess with the style stuff -
> would it be possible to get a style that more closely matches the
> current website style before I commit these changes to the repository?

I'm still working on the content generation.

First you can select a html theme in conf.py:
html_theme = "default"
or sphinxdoc, scrolls, agogo, traditional, nature, haiku, pyramid

Witch one?

Then inspect and play with the css files in doc/_build/_static,
and copy modified files to doc/_static when done.
Preview: http://sphinx.pocoo.org/theming.html

Anyone? We could make a contest.

If that is not enough, we can create a Jinja2 template:
http://sphinx.pocoo.org/templating.html

> This needs to be recorded somewhere useful, but I honestly don't know
> where. Perhaps some "documentation documentation"? :-)

Now all is configurable in doc/conf.py.
TODO: write doc/internal/documentation.txt

> Assuming the sphinx migration goes well (and it appears to be) I'll
> look at replacing all the is_epydoc flag checks with is_sphinx for
> sanity's sake (well, getting rid of the flag would be saner but
> unrealistic at this point.)

+1

> I'm a little confused by the samples discussion:

+1

[Winston Wolff]

I tried this patch out and it does work and generates html docs with events on the Window class page. But there is also a clone of the HG repo dealing with Sphinx conversion here: http://code.google.com/r/chardster-sphinx-docs/source/list

Does anybody know if we should use Txema or not?

-Winston

[Txema Vicente]

Hola.

* Content generation is complete.
* Theme changed. Pretty?

Demo: http://code.nabla.net/doc/pyglet/
Patch: http://code.nabla.net/doc/pyglet/pyglet_sphinx_patch.zip

[Txema Vicente]

Sorry, I started on my own just to see if I could make lists of events,
but I warmed and thought about submitting a patch to celebrate the 1.2
release.

IMHO, It is easy to merge

Richard Thomas:
* ext.autodoc: document bound methods, parsed reprs
* Examples: Custom role, search

Me:
* ext.autosummary: API generation
* EventDocumenter
* Templates

[Winston Wolff]

> Demo: http://code.nabla.net/doc/pyglet/

I really like the new theme--very clean without any extra details to obscure the information.

-ww

[Txema Vicente]

I think documentarion is complete and clean, so ready to commit.

Please check and let me know if you see any problem in the content
generation.

> This needs to be recorded somewhere useful, but I honestly don't know
> where. Perhaps some "documentation documentation"? :-)

http://code.nabla.net/doc/pyglet/internal/doc.html#generation

The replacement of _is_epydoc with _is_doc, the warnings list below, and
other improvements (like examples role), may be others commit.


Warnings
--------

pyglet.app.base.EventLoop.sleep:14: WARNING: Field list ends without a
blank line; unexpected unindent.
pyglet.app.EventLoop.sleep:14: WARNING: Field list ends without a blank
line; unexpected unindent.
pyglet.input.base.Joystick.on_joyaxis_motion:4: ERROR: Unexpected
indentation.
pyglet.input.base.Joystick.on_joyaxis_motion:5: WARNING: Block quote
ends without a blank line; unexpected unindent.
pyglet.input.base.Joystick.on_joybutton_press:4: ERROR: Unexpected
indentation.
pyglet.input.base.Joystick.on_joybutton_press:5: WARNING: Block quote
ends without a blank line; unexpected unindent.
pyglet.input.base.Joystick.on_joybutton_press:5: WARNING: Inline

interpreted text or phrase reference start-string without end-string.

pyglet.input.base.Joystick.on_joybutton_release:4: ERROR: Unexpected
indentation.
pyglet.input.base.Joystick.on_joybutton_release:5: WARNING: Block quote
ends without a blank line; unexpected unindent.
pyglet.input.base.Joystick.on_joybutton_release:5: WARNING: Inline

interpreted text or phrase reference start-string without end-string.

pyglet.input.base.Joystick.on_joyhat_motion:4: ERROR: Unexpected
indentation.
pyglet.input.base.Joystick.on_joyhat_motion:5: WARNING: Block quote ends
without a blank line; unexpected unindent.
pyglet.input.Joystick.on_joyaxis_motion:4: ERROR: Unexpected indentation.
pyglet.input.Joystick.on_joyaxis_motion:5: WARNING: Block quote ends
without a blank line; unexpected unindent.
pyglet.input.Joystick.on_joybutton_press:4: ERROR: Unexpected indentation.
pyglet.input.Joystick.on_joybutton_press:5: WARNING: Block quote ends
without a blank line; unexpected unindent.
pyglet.input.Joystick.on_joybutton_press:5: WARNING: Inline interpreted

text or phrase reference start-string without end-string.

pyglet.input.Joystick.on_joybutton_release:4: ERROR: Unexpected indentation.
pyglet.input.Joystick.on_joybutton_release:5: WARNING: Block quote ends
without a blank line; unexpected unindent.
pyglet.input.Joystick.on_joybutton_release:5: WARNING: Inline

interpreted text or phrase reference start-string without end-string.

pyglet.input.Joystick.on_joyhat_motion:4: ERROR: Unexpected indentation.
pyglet.input.Joystick.on_joyhat_motion:5: WARNING: Block quote ends
without a blank line; unexpected unindent.
tests.test:81: WARNING: Definition list ends without a blank line;
unexpected unindent.
tests.test:89: WARNING: Option list ends without a blank line;
unexpected unindent.
tests.test:98: WARNING: Definition list ends without a blank line;
unexpected unindent.
tests.test:100: WARNING: Option list ends without a blank line;
unexpected unindent.
doc\internal\dist.txt:10: ERROR: Unexpected indentation.
doc\programming_guide\graphics.txt:32: ERROR: Unknown target name:
"opengl programming guide".
doc\programming_guide\input.txt:105: WARNING: Inline interpreted text or

[Winston Wolff]

That looks great. Shall I import it tomorrow (Friday)?

-ww

[Richard Jones]

Please, go for it! :-)


Richard

[Txema Vicente]

Hola.

It is done.

For the record:

The only 2 lines that change in pyglet/__init__.py are:
359 if not _is_epydoc: -> If True:
398 if _is_epydoc: -> If False:
But I suppose that changes break epydoc, it should be cleaned and evicted.

All the rest ! is in pyglet/doc:

- Requires sphinx installed

- conf.py contains standard sphinx configuration, plus:
* patched ext.autosummary taken from sphinx 1.1.3
- Generate new constants for templates.
* Module and member filters.
* Reads directories to create a submodule dict.
* EventDocumenter class
* Save files internals/blacklist.rst, build.rst on each build

- reST entry point is index.txt, and ALL txt files in will be processed,
recursively.

- "make html" will save _build/html/warnings.txt and around 20 Mb more.

- If you change the api generation process, remember to delete the api
and _build folders.

- generated .doctree folder is big and can be deleted.

Now I know reST fu.

Hasta luego.

El 22/06/2012 8:16, Richard Jones escribi�:

[Txema Vicente]

Hola.

I will stop sending to this thread details on the sphinx patch. For now on:

https://code.google.com/r/txema-pyglet-doc/

The generated documentation from this branch will be at:

http://code.nabla.net/doc/pyglet


Cheers