search

blaylockbk / Herbie

Download numerical weather prediction datasets (HRRR, RAP, GFS, IFS, etc.) from NOMADS, NODD partners (Amazon, Google, Microsoft), ECMWF open data, and the University of Utah Pando Archive System.
https://herbie.readthedocs.io/
MIT License
471 stars 73 forks source link

Hosting the documentation at "Read the Docs" #140

Closed amotl closed 1 year ago

amotl commented 1 year ago

Dear Brian,

coming from https://github.com/blaylockbk/Herbie/issues/100#issuecomment-1373204922, I would like to recommend to use Read the Docs for hosting the documentation [^1]. It also has excellent integration with pull requests, by providing a dedicated preview page, and offers the well-known badge which indicates that building the documentation was successful. Other than this, it will also improve the matters outlined at GH-141.

If you agree, I am humbly asking you to sign up at Read the Docs [^2], import the Herbie project, and also add me as a maintainer there. My handle is also amotl on RTD ^3. Then, I can take care of all steps required.

With kind regards, Andreas.

[^1]: I've published many Sphinx documentation sites to self-hosted webspaces in the past, using a Webhook to trigger the rebuild, and a custom Webhook receiver written in Lua, for actually running it on the target host. However, I am gradually moving all Sphinx-based documentation sites for the projects I am maintaining over to Read the Docs, as they are just doing an excellent job on this matter, and it is free for open source projects. Just recently, we've added a corresponding configuration to the Luftdatenpumpe repository with https://github.com/earthobservations/luftdatenpumpe/commit/1fa15082a.

[^2]: I also recommend to sign up to Read the Docs with your GitHub account, so you are all done, and your account is connected, which makes it a breeze to import your repositories. Otherwise, you would need to connect your VCS account manually.

blaylockbk commented 1 year ago

This sounds like a good idea to me; I like the idea that readthedocs will build my pages for me (and for free for open source as far as I understand with the exception of a simple ad).

I merged #142, but RTD fails building the docs. I think because I'm using autosummary which needs to import herbie, and Herbie can't be installed because cartopy can't be installed via pip. Perhaps there is a way around this.

amotl commented 1 year ago

Ah, thanks. I've submitted GH-145 as a probable fix.

blaylockbk commented 1 year ago

fixed by https://github.com/blaylockbk/Herbie/pull/145

amotl commented 1 year ago

It looks like not all documentation artefacts get rendered/published on RTD properly, so you had to add a fix with 5c27db6d0? Do you mind re-opening this issue in order to track that properly, and come up with an appropriate solution?

blaylockbk commented 1 year ago

Yeah, that commit was to fix some direct url links to the docs in the Readme. The pages rendered on RTD, it's just the links in the Readme needed a tweek. I don't think anything was wrong in how the pages rendered. I apologize if I didn't quite understand what you ment by tracking the issue. Is there something else I should have done for this?

amotl commented 1 year ago

Oh I think I got that wrong đŸ¤¦. The links clearly point to RTD. Closing this again.

https://github.com/blaylockbk/Herbie/blob/5c27db6d00eeb3e9943270bf3bf83c32608e00e2/README.md?plain=1#L28-L36