DOC: add guidelines for building the docs

[jorisvandenbossche]

First draft of some guidelines on contributing to and building the docs (following #5934). Comments are very welcome.

Rendered version can be seen here: https://github.com/jorisvandenbossche/pandas/blob/doc-guide/doc/README.rst

TODO:

• update section on Sphinx 1.2 now 1.2.1 is released

[jreback]

sexy!

maybe add how to show the deps: pd.show_versions()

I think this could form the basis for a new major doc section (in addition to a README), say 'Contributing To Pandas'?

(and also add in all of the developer links / docs as well (at some point), so that everything is in the main docs

http://pandas.pydata.org/developers.html (IOW this link would refer back to the Contributing to Pandas page itself)
which would have link for docs / code / intro...etc

[metakermit]

Looks nice so far. I also started throwing in some notes about the things I encounter here.

[jorisvandenbossche]

@jreback Included the show_versions()
And indeed, a larger doc section on ''Contributing To Pandas'' is a very good idea. But that's for later :-)

@y-p @Kermit666 @phaebz Any futher comments, unclear or incorrect guidelines?

[jreback]

@jorisvandenbossche I think you should add as a section to the main docs

(I know you want to reorganize them at some point)....but I think they will get a lot more visibility this way

my 2c. (you can put them near the end)

[ghost]

no need for acthung, it's already a warning.

[ghost]

looks good to me.

[TomAugspurger]

Do we have an official ruling on whether the name of this great library we all work on is ever capitalized? In Wes's book I think it was always lowercase.

[TomAugspurger]

grep -nr Pandas doc/source reveals quite a few uppercase Pandas, so maybe its OK (or those all need to be "fixed").

[jorisvandenbossche]

But I also did it inconsistently :-) (only in the headers with uppercase, in text it was also lowercase). So changed all to lowercase.

[metakermit]

Looks good to me. I left a small comment about the documentation format with a link. I don't know why didn't GitHub put it here as well. Here it is once again just in case:

Numpydoc allows us to format the docstrings in the pandas source code to annotate parameter and return values and present them to users in a more useful format. You can find out more about the sphinx and numpydoc format `here
 +<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ or simply look at some of the existing pandas documentation code to extend it in a similar manner.

[jorisvandenbossche]

I incorporated some of the comments. Thanks for them!

@Kermit666 I think it is because you commented on the the commit. Most of the time comments are added on the "Files changed" tab at the PR, and then it certainly shows up here.

@jreback I added a section on contributing in the main documentation, but for now just included the README.rst so it is visible in the main docs. And this section can then be expanded later.

[jreback]

@jorisvandenbossche 👍

[ghost]

bumped to 0.14.0, not a blocker.

[jorisvandenbossche]

OK, further tweaks/additions can always be made later, merging for now.

[jreback]

@y-p if you have a chance can you rebuild docs at some point?

[ghost]

docs are up.

[jreback]

looks great! thanks

@jorisvandenbossche contributing section looks nice!