Jupyter-book: Citation for Jupyter Book

[emdupre]

Hi @choldgraf and team !

Thanks so much for making jupyter-book -- it's a really exciting initiative ! I'd like to cite it, but I can't seem to find the best way to do so. It looks like you already have releases -- are you using Zenodo to generate DOIs ? Or is there another [paper, poster, etc] that would be better to cite ?

Thanks again !

Elizabeth

[choldgraf]

hmmmmmm.....that's a good point, I haven't ever thought about this :-)

What would you recommend? I could write up a short blurb and submit it to JOSS?

[emdupre]

I'm a big fan of cutting DOIs with Zenodo. The integration is quite easy to set up, too, and means that I could cite your code quickly.

I don't think this would preclude submission to JOSS -- I don't have any personal experience there, but I've heard great things !

[choldgraf]

Cool - lemme check it out and will report back :-)

[choldgraf]

I looked into the guide you linked and, yeah! that is pretty simple!

Two quick questions:

1. Do you know anything about the relative merits of zenodo vs figshare? I know others who have used figshare but I also heard it's not really an open service
2. Do you know how zenodo handles new versions of software? E.g. if I create a DOI for v0.2, do I have to change the DOI for each new version? Is that much of a hassle?

Thanks for your guidance :-)

[choldgraf]

@emdupre pinging you in case you're not watching this thread

[emdupre]

Thanks for checking it out ! To give some (hopefully helpful) answers:

1. I use figshare for presentations (where I want them to by easily visualized in browser) but prefer zenodo for code -- partially because the integration is so easy ! I do know that figshare is privately funded and zenodo is funded through CERN, so I'm not sure if that's why GitHub decided to push the zenodo integration over the figshare one. But it seems to have had an effect, with more code being hosted on zenodo than figshare.

2. If you set up the zenodo integration, as soon as you cut a new release on GitHub it cuts a new DOI on Zenodo. It actually cuts two DOIs for your sotware: one for the "concept" of the library, and one for the specific version. The concept DOI stays stable across all releases, but the version-specific one will update.

   This can make it a (small) pain to keep your docs sync'ed if you're embedding the version-specific DOI badge in your documentation. One solution Chris G came up with that I quite like (and use in my own projects) is to run some javascript and grab the most up to date version-specific DOI through their API. You can see how I'm embedding it in a sphinx site here.

Let me know if that answers your questions, and thanks again :sparkles:

[choldgraf]

ah that's good to know about the 2 different kinds of citations.

I'm thinking of waiting until https://github.com/choldgraf/jupyter-book/pull/38 and https://github.com/choldgraf/jupyter-book/pull/48 and https://github.com/choldgraf/jupyter-book/pull/27 land before cutting a new release. Are you fine w/ the last beta release as the DOI?

[emdupre]

Yes, that's totally fine ! Whatever makes sense to you -- I'm just looking for something to cite :smile:

[choldgraf]

cool - I'll take a pass at this after the holiday!

[shivupa]

Just stumbled upon this, and I wanted to mention that this would also fit perfectly at the Journal of Open Source Education (JOSE) if you decide to submit this somewhere. It's a sibling of JOSS and they say:

"JOSE accepts two types of submissions: (1) computational learning modules, created as open educational resources (OER), and (2) open-source software, created as educational technology or infrastructure. "

[choldgraf]

I agree! Though I've been checking off and on for the last several months and it seemed like they still weren't accepting submissions. Do you know if the submission process is open now?

[shivupa]

Yeah! You should be able to submit here that will start a review process like this which usually has a quick turn around time.

[choldgraf]

@emdupre think the citation can wait until this goes through the JOSE process? :-)

[emdupre]

Totally up to you, but I'm not sure the zenodo DOI would be mutually exclusive, here ! Having a DOI seems to be ok for submitting at JOSS, at least.

[choldgraf]

one more question: if I cut a DOI now, but then move this repository to another org, will that break the DOI?

[emdupre]

That's a great question. I tried looking into it, but I really can't find anything... GitHub will do the automatic redirects, so it might be ok ? But I can't find concrete documentation, sorry !

[choldgraf]

OK, @carreau said that he'd help me get this transfered to the jupyter org next week, so I can make a release once that happens :-)