Fixing incoherent style of references

[sotte]

TLDR: The references in the docstrings have weird/wrong/very different formats. "There should be one-- and preferably only one --obvious way to do it."

I was looking at the reference links of some classifiers when I realized they were not formated correctly. When I was about to submit a pull request I realized that many references have a different format and according to the Zen of Python

There should be one-- and preferably only one --obvious way to do it.

Some references

• are referencable, some not.
• are not wrapped correctly
• have links to the PDFs, some don't, some links are dead.

I think references should be referencable, be as concise as possible (authors, title, conference/book, etc). I'm not sure about the link to the PDFs because the URIs change over time and lead to dead links. What do you think?

My suggestion:

   References
    ----------

    .. [1] Hinton, G. E., Osindero, S. and Teh, Y. A fast learning algorithm
           for deep belief nets. Neural Computation 18, pp 1527-1554.

I'd be willing to spend a few hours on the weekend to fix the references once we decide on how it's supposed to look like.

Also, #3912 should document the format for the references.

[raghavrv]

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?

[amueller]

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.

[sotte]

@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.

[amueller]

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

[sotte]

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.

[amueller]

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?

[sotte]

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

[sotte]

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

[sotte]

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.

[sotte]

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

[raghavrv]

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)

[agramfort]

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
"?

[sotte]

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.

[agramfort]

excellent thanks !

[amueller]

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

[raghavrv]

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

[sotte]

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

[adrinjalali]

We've standardized our docstrings a lot ever since.