Documentation, links, help improvements about rootpy HOT 27 CLOSED

@cdeil I completely agree with everything you have suggested. As for a Q&A site, what are your thoughts on something like http://metaoptimize.com/qa/? http://www.osqa.net/ is open source.

I'll move the docs from my github webspace over to rootpy's and then will devote some of my afternoon to cleaning it up. Instructions on how to update the docs will also be posted.

Thanks in advance for any time you devote to improving rootpy! It's great to see a growing interest in the community!

from rootpy.

@cdeil you are now a member of the rootpy collaboration and have full rights on the repositories. I've deleted the old docs on my github page and will upload docs on http://rootpy.github.com/rootpy/ soon.

from rootpy.

Documentation on how to build and upload the documentation is here:

https://github.com/rootpy/rootpy/tree/master/docs

from rootpy.

We are now live at http://rootpy.org! Also see http://rootpy.org/qa

from rootpy.

Great! Thanks for all your work. I'm still a bit confused, though. :-)

At the moment rootpy.org simply shows the same docs as http://rootpy.github.com/rootpy/, only with a different theme.
I don't see the point in having two sites showing the sphinx docs, is this temporary or do you plan to keep both?
If I follow https://github.com/rootpy/rootpy/tree/master/docs will both pages update automatically?

Do you want rootpy.org to become a webpage separate from the sphinx docs?
I think most open-source projects do this, see e.g. ipython.org and astropy.org .
Of course it is just as well possible to put everything in the sphinx docs, but I think this becomes messy (impossible?) as soon as we have more than one rootpy version out there.
E.g. http://pypi.python.org/pypi/rootpy/ contains rootpy 0.6, which e.g. points to the no longer existing homepage http://ndawe.github.com/rootpy , and I guess there is no 0.6 docs available on the net?

I personally think the astropy page and docs (hosted on readthedocs) look great, I guess if you like it too I'm volunteering to set up https://github.com/rootpy/rootpy-website by copying https://github.com/astropy/astropy-website
Here's some info on their release procedure:
http://docs.astropy.org/en/latest/development/building_packaging.html#release

from rootpy.

I'm sorry, I'm sure it was not trivial to set up, but I don't think the new QA site http://rootpy.org/qa you created is the best solution.
Using an existing QA site has the advantage that there already is a community of ROOT / python / numpy users, a new site has the threshold to finding it and setting up an account, and it seems to me the rootpy community is very small at the moment.
We could e.g. create a tag rootpy on stackoverflow and subscribe to it, i.e. get notified if a user asks a question with this tag.

Here's some options where we could send a user with a question:

--- PyROOT on ROOT Talk: http://root.cern.ch/phpBB3/viewforum.php?f=14
498 threads, no specific thread on rootpy, but rootpy is mentioned in 4 comments.

--- stackoverflow ---
pyroot 0
(although there is one question: http://stackoverflow.com/questions/10057076/access-nested-containers-in-a-ttree-with-pyroot)
root-framework 20
numpy 2,925
scipy 1,026
python 118,911

You pointed out http://metaoptimize.com/qa/, but I had never heard of it and it seems that the community is at stackoverflow:
root 0
numpy 0
scipy 1
python 39

--- http://scicomp.stackexchange.com/ was pointed out as a possible place where numpy might go from now on:
http://old.nabble.com/Meta%3A-help%2C-devel-and-stackoverflow-ts34086169r0.html
Although there doesn't seem to be an existing community yet:

root 0
numpy 3
scipy 0
python 35

I guess the ROOT Talk pyROOT forum would be the most obvious place for rootpy user questions, but I don't know if the pyroot devs would want us there.
Otherwise I think creating a rootpy tag on stackoverflow and pointing users there would be a good and very easy to set up solution.

What do you think?

from rootpy.

Good plan. Let's create the tag "rootpy" on stackoverflow. I already see several questions and answers discussing rootpy... Do you know if it's possible to create a new tag for already existing questions?

I put the docs at rootpy.org mainly as a placeholder but eventually it should turn into a site like ipython.org etc. Your help in doing this would be much appreciated!

from rootpy.

I'll try re-tagging the question that mention rootpy (or where the answer mentions it) with rootpy.

I don't know if this will be accepted:
http://meta.stackoverflow.com/questions/124712/how-to-create-a-new-tag-without-asking-question

It seems they actually recommend having a mailing list (e.g. a google group) as the primary place for user support and only use stackoverflow as a secondary place:
http://meta.stackoverflow.com/questions/19852/use-stack-overflow-as-the-official-support-site-of-an-open-source-project

I can see benefits and drawbacks to having stackoverflow / github issues only and to having mailing list / stackoverflow / github issues.

from rootpy.

I tried to re-tag http://stackoverflow.com/questions/10121233/hdf5-integration-with-root-framework , it didn't work:

"Users with less than 1500 reputation can't create new tags. The tag 'rootpy' is new. Try using an existing tag instead."

I'll start asking and answering questions on stackoverflow, but I guess it'll take a while until I get the 1500 reputation.

from rootpy.

It requires admin rights, so could you please create a new empty repo https://github.com/rootpy/rootpy-website and I'll try to set up a webpage.

I'm still a bit confused about the github pages, it seems that ipython, astropy and most others have a separate repo like https://github.com/ipython/ipython.github.com instead of a gh-pages branch as you set it up.

I don't really know what the advantage is though (see [1]), if it's just about push rights then I don't think it matters for us and we can keep it in a branch as you currently have set it up ( https://github.com/rootpy/rootpy/tree/gh-pages ).

[1] http://www.mail-archive.com/[email protected]/msg34942.html
Fernando Perez: "In particular,
it's important not to use gh-pages like they originally suggest, but
instead like we do it in ipython: the build should be a separate repo
altogether, not just a branch in the official source repo. Ours has
the makefile targets and scripts already for that, let me know if any
of it doesn't make sense."

from rootpy.

scikit-learn also uses a separate repo: https://github.com/scikit-learn/scikit-learn.org. I think I prefer the separate repo for the same reasons they have.

from rootpy.

OK, you'll have to create the new repos.

I'm all for doing it the same way all the other scientific python projects are doing it (with a separate repo).
Just out of curiosity, did you find an explanation why the solution with the separate repo is preferred?

For reference, here is how some other projects make their releases:
https://github.com/scikit-learn/scikit-learn/wiki/How-to-make-a-release
http://ipython.org/ipython-doc/dev/development/release.html
http://astropy.readthedocs.org/en/latest/development/building_packaging.html

from rootpy.

It looks like the separate repo is preferred since it keeps any graphical stuff separate from the code so you are not forced to clone everything with rootpy. Also, different users might end up writing docs than those writing code too at times and separation might make administration easier. We would also have separate issue tracking for the docs and the code.

rootpy.org and docs.rootpy.org repos have been created. I do have a hosting plan and the domain with justhost.com for the year but if we decide to use readthedocs.org I can point he domain there and cancel the hosting plan.

rootpy.org should hold the main website while docs.rootpy.org can either have separate tags for versions of the docs or separate directories like in https://github.com/scikit-learn/scikit-learn.org/tree/master/webroot.

from rootpy.

That makes sense.

I'll try creating a basic first version of rootpy.org tomorrow.

And we need to copy over https://github.com/rootpy/rootpy/tree/gh-pages over to https://github.com/rootpy/docs.rootpy.org and then delete the gh-pages branch, right?
I'd be happy to give it a try, but I'm no git expert and don't want to mess things up.

I don't think readthedocs could host rootpy.org, at least the projects I'm aware that use readthedocs (e.g. astropy) only use it for their project docs. But I'm not 100% sure.

from rootpy.

We can simply delete the gh-pages branch in rootpy since it is automatically generated and then move the contents of docs/ into docs.rootpy.org

from rootpy.

I can't push to the rootpy.org repo.

$ git clone [email protected]:rootpy/rootpy.org.git
Cloning into 'rootpy.org'...
warning: You appear to have cloned an empty repository.
$ cd rootpy.org
$ edit index.rst
$ git add index.rst
$ git commit index.rst 
[master (root-commit) 85bb8d4] Initial commit
 1 file changed, 17 insertions(+)
 create mode 100644 index.rst
$ git push
ERROR: Permission to rootpy/rootpy.org.git denied to cdeil.
fatal: The remote end hung up unexpectedly
$ git remote -v
origin  [email protected]:rootpy/rootpy.org.git (fetch)
origin  [email protected]:rootpy/rootpy.org.git (push)

Maybe you have to give me permissions for that repo or make the initial commit?
Or maybe I have to clone or push differently?

from rootpy.

Looks like you have to add push and pull rights for the rootpy team for the new repos:
https://github.com/organizations/rootpy/teams/135168

from rootpy.

Sorry about that. You can push now.

from rootpy.

Any updates on documentation? At the moment I find it hard to find useful examples and I am forced to look up the code which is not very efficient.

While the QA (http://rootpy.org/qa/) are online, they don't seem to be used and full of spam like this:
http://rootpy.org/qa/questions/79/check-out-the-sitedg-make-your-life-easf-sfs-fsdfsdfdy-check-it-out

from rootpy.

I've been working on docs lately. Sorry for the current lack of info.

For now it's probably best to use the Google mailing list: [email protected] or Stack Overflow (if you can create a new rootpy tag and tag your question)

rootpy.org will be completely overhauled soon with new docs. I will be sure not to erase any questions that already exist on the QA board. Currently attempting to delete the spam...

from rootpy.

Thanks, I'll try the methods you suggested in the future.
I will gladly help you guys out with this kind of stuff once my thesis is done.

EDIT:
Ok, I did as you suggested.

• rootpy-users (google) membership is pending
• new tag at stackoverflow needs 1500 reputation
• current question: http://stackoverflow.com/questions/13143911/plotting-of-2d-histogram-with-rootpy-and-matplotlib

from rootpy.

@kreczko I approved your membership for rootpy-users. A new example is in examples/plotting/plot_hist.py showing how to create variable-width bins etc. I'll take a look at your question on SO. Plotting 2D histograms in matplotlib through rootpy isn't currently supported but this can soon change :) I suppose you are looking for something like imshow() or http://matplotlib.org/examples/mplot3d/hist3d_demo.html ?

from rootpy.

@ndawe Thanks, will post stuff from now on on rootpy-users and on SO. This way we might get enough reputation together to create the tag ;).

As to the 2D plot:
http://matplotlib.org/examples/mplot3d/hist3d_demo.html - is not optimal for what I want to plot, but can be useful.

These are kind of what I'm aiming for:
http://matplotlib.org/examples/pylab_examples/pcolor_demo.html
http://matplotlib.org/examples/pylab_examples/poormans_contour.html
http://matplotlib.org/examples/pylab_examples/hexbin_demo.html
and maybe (in some cases)
http://matplotlib.org/mpl_examples/pylab_examples/matshow_04.png

Shall I create a separate issue for this?

from rootpy.

Just a reminder for myself: if we want to use travis-ci to build our devdocs (which it does perfectly at the moment) we have to upload them to readthedocs or rootpy.org somehow without giving aways a password.

I googled this a bit and it seems we could either use an FTP dropbox or Ge.tt:

• https://groups.google.com/forum/#!msg/travis-ci/c_aI-_uxrik/n9p76qZvDREJ
• http://ge.tt/developers
• https://open.ge.tt/1/doc/rest#files/%7Bsharename%7D/create

from rootpy.

Can't we use the ReadTheDocs service hook?

I guess it has the limitation that RTD can't build the numpy plots, is that why you want to do it on travis?

from rootpy.

Yes, so that the full docs can be created including the running of all the examples and inserting the plots created by any examples.

from rootpy.

Can someone break this into more specific things and mention "#26" in the new issues? I can't tell at a glance what remains and what is a must have for 0.7.

from rootpy.