[pypy-dev] Documentation sprint at PyCon

[holger krekel]

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
>