Minor suggestion : We could have a script (not a test) that could scrape the reference links and verify them all... The script could be run before every release maybe?

The problem with having sphinx referencable references is that sphinx will complain if there are duplicates. On the other hand, we definitely want to list references in multiple docstrings.
Any ideas?

+1 on the general theme though.

@ragv I aggree, one could write a script like that.

@amueller I didn't know that sphinx complains about duplicates.

One could use what should be used for referencing: bibtex. There is sphinxcontrib-bibtex which integrates bibtex into sphinx. However, having a sep. bibtex file also makes the docstring a bit harder to read. And there is another dependency.

Yeah -1 on bibtex. Why is the benefit of having a referenceable reference in the docstring? I think a list would be just fine.

Referenceable reference are nice because you can say things like: "...we did X according to [ref1] and Y according to [ref2]..." ( exmaple)

Alternatively, when only using lists for the references one could just put the name of the first author + year (or something similar) into the brakets.

That would be kind of nice, if the docstrings where that detailed ;)
Can you maybe double check if / how sphinx complains with your original suggestion?

ensemble/bagging.py uses referencable references (great word btw) and they reference the same papers. Seems to work without problems.

So we could use that & a script that checks the if the links to the pdf are alive.

Edit:

• http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#citations

I'd suggest settling for the following:

We implemented method X according to [1]_ and Y according to [2]_.

lorem ipsum...

References
----------
.. [1] AUTHORS.
       TITLE.
       DETAILS.
       URL

.. [2] AUTHORS.
       TITLE.
       DETAILS.
       URL

This is also how scipy does it...most of the time. See http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html#id12

Checking links with sphinx:
http://sphinx-doc.org/builders.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder

Maybe there is no need for an extenal scirpt. Haven't tried it yet.

There are currently 139 non-local redirects and broken links in the docs.

Checking links with sphinx:
http://sphinx-doc.org/builders.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder

Thats awesome!

Hey btw do we need to decide on the order of the papers? (chronological / relevance / alphabetical / simply leave the order as it is)

is there a simple command line way to check the links of the doc? or maybe
differently "how do you use CheckExternalLinksBuilder
http://sphinx-doc.org/builders.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder
"?

Oh, sorry. This is how you do it:

cd doc
make linkcheck

This however currently builds all the docs including plots. But in the end you get the file _build/linkcheck/output.txt.

if the numeric style doesn't give any warnings, I'm all for it.

@sotte hey :) any news on this? :)

@ragv I've been very busy but I'll try to finish it this weekend...

We've standardized our docstrings a lot ever since.