Rasterio: Hosting documentation

[perrygeo]

Read the docs sounds good until you see [their FAQ on C dependencies}(https://read-the-docs.readthedocs.org/en/latest/faq.html#i-get-import-errors-on-libraries-that-depend-on-c-modules) - not keen on mocking and mucking with our setup.py and maintaining yet another build environment.

What about building on travis or building locally and pushing to https://pythonhosted.org/?

What about github pages as an alternative?

[JamesRamm]

If you are building on travis then this will help (for github pages):
https://github.com/Syntaf/travis-sphinx

And would certainly be in favour of getting something done asap - browsing the docs from .rst without any contents/index or search is quite painful. Getting this done will make it more accessible for users & potential contributors (and possibly ease the number of questions in the issues list - which Im increasing responsible for, sorry!)

[perrygeo]

As a temporary hosting solution, I've put the sphinx docs on s3 at https://mapbox.s3.amazonaws.com/playground/perrygeo/rasterio-docs/index.html

@JamesRamm thanks for the tip on travis-sphinx - that could come in handy. Don't worry about the number of questions on the issues list; every question, every bug report is an opportunity to improve the software so I encourage you to keep those discussions coming!

[sgillies]

/cc @robintw

Let's go ahead at the sprint with using travis-sphinx to deploy to GitHub pages.

Question for you @perrygeo: how much do our docs depend on being able to import rasterio? It would be ideal if we could develop the docs in an extremely stripped-down gh-pages branch, docs-only, no code, in order to speed up doc builds. Is that possible? Is it a good idea?

[perrygeo]

How about ghp-import which lets you build static sites from your master branch and publish to gh-pages without manual branch juggling.

Untested, but based on scripts that have been know to work in the past :-)

$ cd docs
$ make html
$ ghp-import _build/html -m "New docs"
$ git push origin gh-pages

[sgillies]

@perrygeo I just tried ghp-import and I think it'll work fine for us. I'm going to push to gh-pages now.

[sgillies]

Here we go: https://mapbox.github.io/rasterio/. I'm going to close this. We'll create new documentation tickets for the sprint.

[astrojuanlu]

I went to the docs and saw that the last version is still 1.0a9. Would you be interested in switching to Read the Docs, in the same vein as https://github.com/Toblerity/Shapely/pull/506? I guess similar questions regarding the domain name will arise (https://github.com/Toblerity/Fiona/issues/258)

[sgillies]

@crazyzlj: can you please delete https://readthedocs.org/projects/rasterio/ ? It is blocking the rasterio project from publishing documentation on Read the Docs. As soon as you do, I will begin publishing official project documentation. Thanks for your help!

[sgillies]

Rasterio's docs are ready for RTD, staged temporarily at http://the-real-rasterio.readthedocs.io/en/latest/index.html. All we need now is action on deleting the pre-existing RTD project, requested above ⬆️

[crazyzlj]

@sgillies I am very sorry for the delayed reply. I have deleted the test project on readthedocs. I apologize for any inconvenience caused to you by my unintentional experiments.

[sgillies]

@crazyzlj no problem! I understood your experiment as a sign of interest and in the project and am grateful for that.

Here we go: https://rasterio.readthedocs.io/en/latest/.