[pypy-dev] Documentation sprint at PyCon
holger krekel
holger at merlinux.eu
Fri Mar 18 14:32:19 CET 2011
Hey David, Laura, Armin,
nice work!
I just removed the documentation tests now that sphinx performs link-checking.
I noticed that the :config:`OPTNAME` was not ported to sphinx. It generated
a link to the appropriate config option. Maybe some one can port
it or we can just manually replace the few places where it is used.
The docutils role-registering code is in pypy/config/makerestdoc.py
and is a bit involved - maybe Carl Friedrich can tell if this is
still neccessary.
If someone takes care for setting up readthedocs or some other
place to generate the docs i can point the doc.pypy.org domain
name to it.
cheers,
holger
On Thu, Mar 17, 2011 at 14:20 -0400, David Malcolm wrote:
> 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
>
> _______________________________________________
> pypy-dev at codespeak.net
> http://codespeak.net/mailman/listinfo/pypy-dev
>
More information about the Pypy-dev
mailing list