Documentation building and some doc additions

[jankatins]

Try to add some documentation build: mostly reused from pandas.

• Adding three new sections to contributing: "How to contribute via pull requests", "how to add unittests" and "some git commands"
• add __ALL__ property to each python file to declutter the namespace after a from ggplot import *

Open Issues:

• decide on one dialect for docstrings -> numpydocs
• check some errors in the current doc strings
• find out why ggplot.* methods are not added to the docs -> it seems that this was a problem with the order the sphinxext are set in conf.py -> all problems with this are gone
• fix the build warnings -> see above
• add a ggplot.version, which is then used in docs/make.py and also in setup.py

-> Ready to merge :-)

[jankatins]

@glamp Please check if that is what you want :-) I just wanted to have something to point new contributer to.

[glamp]

This looks really good! Is this something that would be hosted on pypi or on another site?

We have docs page in the works but it's probably still about a month away. It will be more of a "how to/quick start" rather than API docs.

[glamp]

I really like the docstrings for pandas and I think that it would be a good place to start given that all of our users will be using pandas.

[glamp]

Totally agree. The * namespace is really cluttered. __ALL__ seems like a good approach.

[jankatins]

pandas (as well as matplotlib) uses numpydocs, so an additional depency (or a included file in docs/sphinxext)

Hosting: not sure how: pandas uploads docs to their homepage (there are some additional commands in make.py in pandas, which do these). Do you have some webspace for this?

My current plan is to use the ggplot2 docs and testcases and port them over to ggplot as new tests, docstrings and examples (like the ggplot2 documentation). That should give fairly complete coverage of the ggplot2 syntax and commands.

[glamp]

hmm. i don't like the extra dependency.

hosting is easy. we've got plenty of spots we can use. plus there'a always
github pages: http://yhat.github.io/ggplot/

On Mon, Dec 2, 2013 at 4:25 AM, JanSchulz notifications@github.com wrote:

pandas (as well as matplotlib) uses numpydocshttps://pypi.python.org/pypi/numpydoc,
so an additional depency (or a included file in docs/sphinxext)

Hosting: not sure how: pandas uploads docs to their homepage (there are
some additional commands in make.pyhttps://github.com/pydata/pandas/blob/master/doc/make.pyin pandas, which do these). Do you have some webspace for this?

My current plan is to use the ggplot2 docs and testcases and port them
over to ggplot as new tests, docstrings and examples (like the ggplot2
documentation). That should give fairly complete coverage of the ggplot2
syntax and commands.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/109#issuecomment-29603884
.

[jankatins]

Pandas had the dependency included but is currently trying to get back to the upstream one: pandas-dev/pandas#5221 One could write a update_numpydoc() function which would be used after clean()...

The other way would be to use the normal sphinx syntax, although looking at the second link below I would really like to use numpydoc :-)

https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
http://codeandchaos.wordpress.com/2012/08/09/sphinx-and-numpydoc/

Re hosting: Your call where to put it :-)

[jankatins]

@glamp Fixed all the doc build warnings/ problems and all the todos. From my point of view it is ready to be merged. It uses a external numpydoc: if you want to change that so no new external depency is introduced, I would would vote to include the relevant files directly in docs/sphinxext and add a make.py#update_numpydoc target.

Please review the changes in docs/contributing.rst as I also slipped in some content changes.

[jankatins]

If you want to have something to upload it: pandas has this in docs/make.py:

def upload_dev():
    'push a copy to the pydata dev directory'
    if os.system('cd build/html; rsync -avz . pandas@pandas.pydata.org'
                 ':/usr/share/nginx/pandas/pandas-docs/dev/ -essh'):
        raise SystemExit('Upload to Pydata Dev failed')


def upload_dev_pdf():
    'push a copy to the pydata dev directory'
    if os.system('cd build/latex; scp pandas.pdf pandas@pandas.pydata.org'
                 ':/usr/share/nginx/pandas/pandas-docs/dev/'):
        raise SystemExit('PDF upload to Pydata Dev failed')

[jankatins]

Any news here? The last commit needs a update (now it's 0.4.2), but that could also be done in the another commit after merging.

Re the dependencies on numpydoc and iypthon for doc building: I see three possibilities:

• Embedded the py files (two files/ + no new dep / - bit rot as in the pandas case)
• use a submodule (- seems to be still fragile (needs code in setup.py -> see e.g. ipython), one extra step on checkout // + no bit rot, is included in the source tar.gz)
• use these as a dependency (- new dep for doc building (who does?) // no bit rot, no fragile git submodule)

I would currently go for the last case, as I don't think that so many people compile the source (vs. search online) and the few would probably have numpydoc installed as it is also used in other projects which are currently much more visible (ipython, pandas)

[jankatins]

rebased on current master and changed the ggpot.version to 0.4.2

[glamp]

ok. so is this ready to merge?

On Tue, Dec 10, 2013 at 4:51 PM, JanSchulz notifications@github.com wrote:

rebased on current master and changed the ggpot.version to 0.4.2

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/109#issuecomment-30271754
.