Doc/update readme #778
Doc/update readme #778
Conversation
There was a problem hiding this comment.
I would like to keep the README as concise as possible. I suggest moving the most important articles to their own documentation page "How to Cite", where we can additionally provide a Bibtex file. I also find a lot of the formulations convoluted and not helpful. This is not due to this PR, but I suggest cleaning things up a bit as we are touching the README now 🙃
README.md
Outdated
| If you use CLIMADA please cite (in general, in particular for academic work) : | ||
|
|
||
| The [used version](https://zenodo.org/search?page=1&size=20&q=climada) | ||
| The [used version](https://zenodo.org/search?page=1&size=20&q=climada) and/or the following published articles depending on which functionalities you made use of: | ||
|
|
||
| - *Impact calculations*: Aznar-Siguan, G. and Bresch, D. N., 2019: CLIMADA v1: a global weather and climate risk assessment platform, Geosci. Model Dev., 12, 3085–3097, [https://doi.org/10.5194/gmd-12-3085-2019](https://doi.org/10.5194/gmd-14-351-2021 | ||
| ) | ||
|
|
||
| - *Cost-benefit analysis*: Bresch, D. N. and Aznar-Siguan, G., 2021: CLIMADA v1.4.1: towards a globally consistent adaptation options appraisal tool, Geosci. Model Dev., 14, 351-363, [https://doi.org/10.5194/gmd-14-351-2021](https://doi.org/10.5194/gmd-14-351-2021 | ||
| ) | ||
|
|
||
| and/or the following published articles: | ||
| - *Uncertainty and sensitivity analysis (unsequa)*: Kropf, C. M. et al., 2022: Uncertainty and sensitivity analysis for probabilistic weather and climate-risk modelling: an implementation in CLIMADA v.3.1.0. Geoscientific Model Development 15, 7177–7201, [https://doi.org/10.5194/gmd-15-7177-2022](https://doi.org/10.5194/gmd-15-7177-2022 | ||
| ) | ||
|
|
||
| Aznar-Siguan, G. and Bresch, D. N., 2019: CLIMADA v1: a global weather and climate risk assessment platform, Geosci. Model Dev., 12, 3085–3097, https://doi.org/10.5194/gmd-12-3085-2019 | ||
| - *LitPop exposures* : Eberenz, S., et al., D. N. (2020): Asset exposure data for global physical risk assessment. Earth System Science Data 12, 817–833, [https://doi.org/10.3929/ethz-b-000409595](https://doi.org/10.3929/ethz-b-000409595) | ||
|
|
||
| Bresch, D. N. and Aznar-Siguan, G., 2021: CLIMADA v1.4.1: towards a globally consistent adaptation options appraisal tool, Geosci. Model Dev., 14, 351-363, https://doi.org/10.5194/gmd-14-351-2021 |
There was a problem hiding this comment.
I suggest moving this into the documentation, maybe on its own page. I think this is too detailed information for a README. There, we can also provide, e.g., appropriate Bibtex entries
Co-authored-by: Lukas Riedel <[email protected]>
Co-authored-by: Lukas Riedel <[email protected]>
Co-authored-by: Lukas Riedel <[email protected]>
Co-authored-by: Lukas Riedel <[email protected]>
|
In order to make the links work in the docs and on the GitHub front page, we'll probably have to move both, CITATION_GUIDE.md and REFERENCES.bib to the root directory and symbolically link them within doc/misc. |
|
@peanutfun : do you like the proposal so far? |
There was a problem hiding this comment.
Content-wise, I agree. But I have a few technical points:
- Why are you using the
[link](link)pattern? If you don't want to replace the link with text, you can just enter the link. It will be rendered as link automatically. - There are a few instances where you use a "here" link, which is highly discouraged
- To avoid the symlink-issue, I suggest making the citation guide an RST file which is only included in the documentation. The link in the README can then point to the appropriate readthedocs documentation page. I can do that.
- Currently, the citation guide document is not included in the Sphinx TOC tree and hence does not appear in the docs. I can fix that.
No good reason then. I didn't know this always works. Thanks!
While I do not fully agree with the strong opinion of this stack exchange, one can change it no problem.
May I ask what you mean by " is only included in the documentation."?
Cool thanks! |
An RST file is not properly rendered by Markdown readers, see e.g. https://github.com/CLIMADA-project/climada_python/blob/main/doc/index.rst We currently link from |
|
I understand. Thanks for the explanation. Makes sense to me! |
* Make citation guide an RST document. * Add table for recommended publications. * Rename REFERENCES.bib to climada_publications.bib * Add citation guide to documentation toctree.
I did both things and brushed up the citation guide a bit. |
# Conflicts: # doc/misc/README.md
|
🙌 very nice. |
Changes proposed in this PR:
This PR fixes #
PR Author Checklist
develop)PR Reviewer Checklist