Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doc/update readme #778

Merged
merged 12 commits into from
Sep 11, 2023
Merged

Doc/update readme #778

merged 12 commits into from
Sep 11, 2023

Conversation

chahank
Copy link
Member

@chahank chahank commented Aug 30, 2023

Changes proposed in this PR:

  • Small update of the readme including a clearer reference list.

This PR fixes #

PR Author Checklist

PR Reviewer Checklist

peanutfun
peanutfun requested changes Aug 31, 2023
View reviewed changes
Copy link
Member

@peanutfun peanutfun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Comment on lines 56 to 61
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
chahank and others added 5 commits August 31, 2023 15:36
@chahank @peanutfun
Update README.md
debee1a 
Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>
@chahank @peanutfun
Update README.md
61fc284 
Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>
@chahank @peanutfun
Update README.md
2026567 
Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>
@chahank @peanutfun
Update README.md
1632680 
Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>
Add citation guide
6dc8ec0
@emanuel-schmid
Copy link
Collaborator

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.
Analogous to AUTHORS.md, CHANGELOG.md and CONTRIBUTING.md.

@chahank
Copy link
Member Author

chahank commented Sep 1, 2023

@peanutfun : do you like the proposal so far?

peanutfun
peanutfun requested changes Sep 4, 2023
View reviewed changes
Copy link
Member

@peanutfun peanutfun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@chahank
Copy link
Member Author

chahank commented Sep 4, 2023

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.

No good reason then. I didn't know this always works. Thanks!

* There are a few instances where you use a "here" link, which is [highly discouraged](https://webmasters.stackexchange.com/questions/7114/how-to-avoid-click-here-links)

While I do not fully agree with the strong opinion of this stack exchange, one can change it no problem.

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

May I ask what you mean by " is only included in the documentation."?

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

Cool thanks!

@peanutfun
Copy link
Member

May I ask what you mean by " is only included in the documentation."?

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 README.md directly to CONTRIBUTING.md, since both are Markdown and can be rendered on GitHub or a local Markdown renderer, in case somebody downloaded the repo. When the file becomes an RST, it is only readable once "compiled" into the docs. Therefore, I suggest the README.md should linke to the online doc page instead of the local file.

@chahank
Copy link
Member Author

chahank commented Sep 4, 2023

I understand. Thanks for the explanation. Makes sense to me!

@peanutfun
Update citation guide
7d50dfe 
* Make citation guide an RST document.
* Add table for recommended publications.
* Rename REFERENCES.bib to climada_publications.bib
* Add citation guide to documentation toctree.
@peanutfun
Add documentation link for citation guide to README.md
b7d481f
@peanutfun
Copy README.md to doc/misc/README.md
8f762ed
@peanutfun
Copy link
Member

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

I did both things and brushed up the citation guide a bit.

@emanuel-schmid
Merge branch 'develop' into doc/update_readme
4dc1a3c 
# Conflicts:
#	doc/misc/README.md
@emanuel-schmid
Copy link
Collaborator

🙌 very nice.

@emanuel-schmid emanuel-schmid merged commit 525842d into develop Sep 11, 2023
5 checks passed
@emanuel-schmid emanuel-schmid deleted the doc/update_readme branch September 11, 2023 09:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@peanutfun peanutfun peanutfun requested changes

@emanuel-schmid emanuel-schmid Awaiting requested review from emanuel-schmid

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@chahank @emanuel-schmid @peanutfun