[pypy-dev] Documentation sprint at PyCon

David Malcolm dmalcolm at redhat.com
Thu Mar 17 19:20:20 CET 2011


Laura, me, and others sprinted on documentation cleanups at PyCon, using
  https://bitbucket.org/dmalcolm/pypy-dmalcolm
as a development branch.

Laura and Armin just merged the changes from that repo

Significant changes are:
  - the Sphinxification of the docs
  - the renaming of the sources from .txt to .rst, to play better with
text editors with smarts for rst
  - organizing the documentation, to try to stress the high-important
up-to-date material, whilst moving the more out-of-date materials to a
clearly-marked annex (see cleanup.rst).

Running:
   make html
within pypy/docs should now generate the documentation part of the site.

You can also use:
   make linkcheck
to check links; we believe we've fixed all internal links, but some
external links are still broken.

There's a nasty hack for pointing at sources which you can see in:
  https://bitbucket.org/pypy/pypy/changeset/c6f7ecf2dc01
but fixing this properly looks like we would need to write a new sphinx
plugin; as it is, it works, but is ugly at the rst level.

Going forward, our idea is that http://docs.pypy.org ought to point at
the sphinx-generated html, and the "development" link on pypy.org should
point to docs.pypy.org (moving another thing off of codespeak).

The folks at readthedocs.org have offered hosting space, and can keep
  http://pypy.readthedocs.org
up-to-date with a nightly build of the documentation.

They have some docs on setting up a CNAME for this:
http://read-the-docs.readthedocs.org/en/latest/alternate_domains.html#cname-support
so that docs.pypy.org can be set up to point there.

Currently that site has an out-of-date build of my bitbucket branch I
mentioned at the top of this mail (and there've been a lot of changes
since then).

Someone will need to sync up with the readthedocs folks to make their
site points at the correct bitbucket repo, and to ensure that it's
getting regularly rebuilt

Hope this makes sense and is helpful.
Dave




More information about the Pypy-dev mailing list