Example documentation update

[lfoppiano]

Hi, I have added some information in the example's directories on how to build it.

Cheers Luca

[MSusik]

Thank you for your PR.

What's the reason for leaving the .rst format in favour of .md?

[lfoppiano]

I've could not use the github markup, with links and so on, so I've opted to rename them .md.

[MSusik]

I've could not use the github markup, with links and so on, so I've opted to rename them .md.

We prefer .rst as it is richer.

[lfoppiano]

Indeed it builds, but I could not manage to run it (see #87 ). I'm not a python expert, so I might be wrong, but dict.iteritems() has been removed in Python 3. See this: http://stackoverflow.com/questions/13998492/iteritems-in-python#13998534

[MSusik]

OK, now I understand.

Basically, the library works for Python3, but the examples are not Python3 compatible. I will fix it soon as this might cause the problems that you already had.

[lfoppiano]

Indeed. :+1:

Regarding the libraries, yes, but I had to install them manually, because the setup was requesting them.

[MSusik]

https://github.com/inspirehep/beard/pull/90 should fix Python3 compability

Regarding the libraries, yes, but I had to install them manually, because the setup was requesting them.

Can you tell me more in detail what happened? python setup.py install should install dependencies automatically for you.

[MSusik]

Inactive

[lfoppiano]

Sorry, I missed your question. The setup was stopping saying that there was no numpy/whatever library.

[jacquerie]

Yeah, @kaplun, this is the problem I was talking about. Since beard depends on scikit-learn we're going to run in variations of #80 if you first don't install numpy and scipy. I think we should point to http://scikit-learn.org/stable/install.html in the installation instructions.

[MSusik]

@lfoppiano I managed to reproduce your problem:

ImportError: Numerical Python (NumPy) is not installed.
scikit-learn requires NumPy >= 1.6.1.
Installation instructions are available on the scikit-learn website: http://scikit-learn.org/stable/install.html

It seems that scikit-learn doesn't install its numpy requirement. We'll see how we can solve this problem.

[kaplun]

IIRC scikit-learn doesn't install any numpy in order not to force installation of an under-performant flavor (since the preferred way is through Anaconda).

So probably there is no automatic solution to our problem?

[glouppe]

Since both numpy and scipy are common requirements of scikit-learn and beard, how could this be an issue? @MSusik Do you understand why setup.py does not automatically take care of this?

[MSusik]

Sorry for the delay

@glouppe Apparently there is no way of ensuring that the dependencies in install_requires are installed in a desired order. Somehow the dependency resolving algorithm in pip seems to even prioritize installing scikit-learn in front of numpy.

One might think that it should be possible to fix this by adding the more important dependencies to setup_requires - a field that lists all the dependencies that should be installed before anything else happens in setup.py. Unfortunately packages installed like this are not available for the packages listed in install_requires :angry: https://pythonhosted.org/setuptools/setuptools.html#new-and-changed-setup-keywords

Maybe we should approach the problem from the other side. We all know that installing beard with its all dependencies with pip is not the desired solution. Perhaps we should throw a warning stating that firstly the user should install conda. Or throw a warning that a good numpy installation is required before continuing with setup.py.

[lfoppiano]

Guys, from my point o view (as a user) you could just add a note in the documentation ;-) and that plus the message I would eventually get, will do.

My 2 cents. Luca