Codecov Report

Merging #8293 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #8293   +/-   ##
=======================================
  Coverage   86.92%   86.92%           
=======================================
  Files         384      384           
  Lines       57995    57995           
  Branches     1060     1060           
=======================================
  Hits        50413    50413           
  Misses       6967     6967           
  Partials      615      615

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 52d1c24...b95e602. Read the comment docs.

I guess this PR shows what was brought up in #8221, that the main astropy page is not http://www.astropy.org/ (where the link does exist).

Anyway, I agree that we should add a note here as well; I'm not 100% sure about the need of it standing out so much, as I think the main goal is less to remind people that they should cite (which I am not very confident is easy), but rather make it super-easy to find how to cite if one wants to. So, perhaps just a sentence like on astropy.org would suffice? I we do want it to stand out, I would use .. Note: instead of .. Important:, as that makes it stand out just as much but doesn't feel so in-your-face.

Separately, we should probably adjust the acknowledge & cite section to include the standard way it is nowadays done for AAS journals (via the \software macro). It is probably also the right place to tell why it is important to cite.

I'll be interested to see other opinions, but I think the issue of acknowledgement and citation is very important to the sustainability of the project. Indeed getting people to cite is not easy, so that is exactly why I think it is worth several cm of valuable screen real-estate. I don't take it lightly putting something there.

I'll note that the wikipedia pop-up asking for support is bigger, red, and more annoying, but I understand why they do it and I have actually given in and donated more than once. I actually thought about a more extreme version of this PR where every top-level page gets the "please cite us" note, but that indeed could be too much. OTOH maybe putting the note at the bottom of each such page would be OK.

The wikipedia one only comes up every year or so (and yes, I donate too, it is well worth it). Anyway, I agree with you this should be easy to find and quite visible; my main rationale is that I think that, effectively, we have not tried anything yet, since most people will nit visit the overall astropy page. Hence, we also do not yet know how glaring and in-your-face we have to be.

Hopefully once we switch to the new site (which I may misunderstood whether the plan with the docs, or only affects learn?), I suppose it's easier to have a cite us link somewhere on the frames.

If this switch doesn't affect the docs, what about adding a link to the top bar? Or in fact sharing the same top bar we have for astropy.org?

Btw, I very much like the scikit-learn solution for this. The "please cite us" is explicit, and is on every page, yet it's not wikipedia agressive. (https://scikit-learn.org/stable/modules/classes.html)

I personally like the banner as added by @taldcroft - maybe if there was a way to have just the green box without the 'important' heading it might be visible without being too visible.

The new learn.astropy.org site will be a new portal for the tutorials and other materials, not a replacement for docs.astropy.org.

I feel like we could also use a "Donate" button in that box but that is discussion for another day... 😛

The new learn.astropy.org site will be a new portal for the tutorials and other materials, not a replacement for docs.astropy.org.

well, in that case I feel it would be super useful to hack in the menubar from astropy.org to docs.astropy.org, and add a cite one to that one.
That would actually solve #8221, too, having a link to the affiliated packages from every page without creating a duplication.

Well, I feel very proactive this morning, and given there wasn't a strong opposition for this, I'm merging as is. Any further enhancement (removing "Important", adding the menubar instead, etc) can be done in follow-up PRs.

thank you @taldcroft!