DOC: easing building of the docs for contributors

[jorisvandenbossche]

Contributing to the docs (and so building the docs) should be as easy as possible to promote this, which is not always the case (eg see comment here #5530 (comment)). Thanks to @y-p to pushing some things forward yesterday, and I thought of making an overview of all issues related to this:

• Building of the docs fails with current stable sphinx 1.2 (DOC: docs don't build with new Sphinx version 1.2 #5899).
  • It does work with 1.1.3 and with development version of sphinx (bug already fixed). In Fixes to docs, eliminate scikits.timeseries docs dep, sphinx 1.2, update copyright years #5921 there was a discussion on this (removing template class.rst would temporarily solve this, but some of the generated docstring pages would be lost). For the moment this is left as is. At least, there should be a clear warning for this.
    Does somebody see another solution?
• On Windows, doc building fails on some unicode error in io.rst (doc generation fails on windows #5142).
  • See also Make doc compiling under windows workable #5245 and DOC: make io.rst utf8 only #5926.
  • Fixed by Rebase ipython_directive on top of recent ipython updated version #5925.
• On Windows, the removal of temporary files cause errors (DOC: error 'being used by another process' when removing temp files on Windows #5933).
• Building of the docs is not python 3 compatible at the moment (Building docs SyntaxError #5479, sphinxext py3 compatibility #5530)
  • This should be solved after updating to ipython's version (DOC: use Sphinx extension directly from numpy/ipython instead of maintaining our own version #5221, Rebase ipython_directive on top of recent ipython updated version #5925)
• There should be a better guide to building the documentation.
  • To be fixed by DOC: add guidelines for building the docs #5996.

Any others?

[jorisvandenbossche]

@Kermit666 If you encounter other issues, unclear things, .. while building the docs, certainly share your experiences! So we can make it easier to start contributing to/building the docs for everyone.

[jorisvandenbossche]

Regarding to more complete guide to contributing/building the docs, where should this best go?

• Expanding the section on the developer pages on the website (http://pandas.pydata.org/developers.html#contributing-to-the-documentation)
• adding a 'CONTRIBUTING.md' in the pandas/doc folder,
• adding a section to https://github.com/pydata/pandas/blob/master/CONTRIBUTING.md
• adding a wiki page
• or ..?

[jreback]

+1 on all these as they are all potential landing points

(maybe have the main CONTRIBUTING pull in a pandas/doc one so they are kept in sync?)

[metakermit]

Also, related to problems with building we talked about in #5530 (comment), I'd also want to clarify what are the steps necessary to rebuild pandas after the source has changed (new branch, git pull etc.) and put it clearly in the README.md file. From what I gather (please correct me if I'm wrong):

• pip install -e . - it will initially build the extensions, link the module in site-packages and install any dependencies. On subsequent code changes it won't rebuild the extensions.
• python setup.py develop - like the above, only it won't even install the dependencies
• python setup.py build_ext --inplace - it will only (re)build the extensions - the ipython module wont be linked in site-packages and no dependency will be pulled.

So one should initially pip install -e and then for any future change call build_ext.

[jorisvandenbossche]

@Kermit666 Is this pip install -e necessary? I never did it. Isn't it equivalent to python setup.py develop? (ok, maybe better phrased: you can choose one of the two first steps). So once you have done that initially, only the third step is needed after updating to latest master.

But I agree that it can be explained better in the developer pages.
Can you also have a look at #5996?

[mroeschke]

Building the documentation is well documented, and since there's only one issue left, will close this issue and let that issue stand. Closing.