More recent API docs needed.

[technorama]

Users are confused when reading API documentation that doesn't match HEAD. An extra link to the current (development, unstable, or other name) API vs released API would be helpful.

[jhass]

Maybe we can find a way to make more clear that it's for the current release (and which that is)? And that you can build local docs with make doc?

[asterite]

It's been 13 days since the last release :-)

[technorama]

@jhass Ease of use should be a goal of ours. More steps == more friction == more frustration == fewer users.

@asterite There are already people on irc asking where TimeThis went. CGI and HTTP is in the process of being refactored. Think about how much of the API naming has changed in 13 days and what it will look like after 20.

One additional link on the website wouldn't hurt anyone but would help those new to crystal. Actually it would help everyone using the project and save them the extra steps in generating their own docs.

[ysbaddaden]

I tend to agree here. Since Crystal changes so fast sometimes, it would be convenient to have an edge version of the API. I have no idea how complicated it would be to put in place, thought.

[jhass]

We already automatically generate the gitbook, we probably could add a Travis build that regenerates docs and pushes any changes to it, shouldn't be too hard. If that sounds like a good idea to everybody I can look into it.

[vyp]

@jhass Sounds good to me. :+1:

[asterite]

@jhass If you want to try this, please do it :-)

I guess this will go into the github pages branch, right? Wouldn't that produce a huge commit history for that branch? For every commit, the docs will be regenerated. All doc pages have embedded a commit hash in every link, so all pages change. I think that would be devastating.

Maybe we should find a way to host this in a non-revisioned place. The same would go for the regular API docs.

[jhass]

Mmmh, true we would probably need to host it somewhere else or force push gh-pages all the time, let me think about it for a while.

[jhass]

Okay after looking through the deployment docs of Travis I see the following opportunities:

• Move the website to Amazon S3, add a build that prepares everything and then uploads it. I can assist in writing that build, but I can't fully set this up on my own.
• We can do the same as above but also with the interesting looking Divshot, Travis docs
• Same should go for GCS (Google's equivalent to S3 basically), Travis docs
• Same should go for Rackspace's equivalent to S3, Travis docs
• Instead of uploading to any of the aforementioned services, we can also use the script deployment to upload to something custom. That could be
  • Your favorite webhoster with FTP access
  • Your favorite webhoster with SSH access
  • A (for now cheap, for example from http://lowendspirit.com/) VPS that hosts the site, upload via the aforementioned methods, or
  • rsync'ing the new site in place via SSH
  • With recent Git versions you can push to a checked out branch, so we could have a custom repo and push to it from Travis (again via SSH), that would be easier compared to the more traditional approach of having a post receive hook on the server that deploys the updated branch. That repo would either be distinct from the main repo or be the main repo with a branch that's never pushed to Github.

In any case an easier first iteration should be keeping the gh-pages branch for the website and the docs and using any of the above methods to provide http:/api.crystal-lang.org and http://api.crystal-lang.org/edge (essentially mirroring what Rails does with api.rubyonrails.org and api.rubyonrails.org/edge).

My personal preference would tend to go to the last option mentioned, followed by S3. But I don't think I should decide this :)

[refi64]

Ok...so I'm not sure how you guys feel about stuff like this...

But have you ever tried ReadTheDocs? It has Markdown support. The server automatically rebuilds your docs every time a commit is made and manages the versions for you. I've used it plenty of times, and it's really freaking awesome. You can use redirects and all that stuff, so all the links could stay the same.

Only real issue is that I'm not sure how you guys would feel about using a doc system written in Python that is scripted via Python...

[jhass]

@kirbyfan64 this is not about http://crystal-lang.org/docs, which is rebuild on every commit to it automatically already and we have no issue with it. This is about http://crystal-lang.org/api

[refi64]

@jhass Still the sane response. :)

[bcardiff]

Maybe we could handle this with a http://www.docrystal.org/ approach (or even with the code, although it's not crystal...) supporting edge + tags (+ branch ?) for either crystal and any other shard. There are some details regarding which version of crystal use to build the docs, but that can be pushed after 1.0 ;-)

[jhass]

@waj agreed on IRC to go for the S3 route. So after creating the bucket and pointing http://api.crystal-lang.org to it, something like

diff --git a/.travis.yml b/.travis.yml
index 6bb746a..a53dba6 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -12,7 +12,7 @@ matrix:
 before_install: bin/ci prepare_system
 install: bin/ci prepare_build
 script:
-  - bin/ci with_build_env 'make crystal spec'
+  - bin/ci with_build_env 'make crystal spec doc'
   - bin/ci with_build_env 'find samples -name "*.cr" | xargs -L 1 ./bin/crystal build --no-codegen'
 branches:
   only:
@@ -28,3 +28,14 @@ notifications:
       - "%{repository_slug}#%{commit} (%{branch} - %{commit_subject}): %{message} %{build_url}"
   slack:
     secure: Ng3nTqGWY+9p1pS6yjGqDhmRvdgbIZgTNpMWbO/ngwpCyicmD3jafZkShqqXbULZTJJr3OxIGzi6GHGusT0Ic/Pi9JCM3X3v/xuBruKIR+EnNyPo7IL4ZYAlwnXyJHlCHHDBq0gSHGvGJwsXn6IgZBPRfeIq+CCyQHVPyvc9EHE=
+deploy:
+  provider: s3
+  access_key_id: foo
+  secret_access_key: bar
+  bucket: crystal_api
+  local-dir: doc/
+  upload-dir: edge/
+  acl: public_read
+  on:
+    repo: manastech/crystal
+    condition: $ARCH = x86_64

should be enough for now. The secret should be encrypted with help of the travis gem. An example ACL for the keys can be found at http://docs.travis-ci.com/user/deployment/s3/#S3-ACL-via-option

Then initially upload the current api/ folder of the gh-pages branch to the root of the bucket. On future releases copy the contents of the edge/ folder into the bucket root.

[will]

A bit of a derail, but if we're uploading things to s3 from travis, can we also upload a tgz of crystal-head? Then we could let people test their projects with the last released versions and head on the community travis support.

[jhass]

Given this extremely low hanging fruit is still open, I added rebuilding API docs to the nightly buildjob for now: http://nightly.crystal-lang.org/api/

[pkorotkov]

@jhass Oh, great news! Would you please explicitly indicate somewhere the repo revision this documentation is built for?

[jhass]

@pkorotkov I'd say that should be implemented by the documentation browser in general, feel free to open a distinct issue. For now you can infer it from the "View source" links.

[asterite]

This is fixed now, thanks to efforts by @bcardiff and @waj:

• Master docs: https://crystal-lang.org/api/master/
• Versioned docs: https://crystal-lang.org/api/0.18.6/
• Latest released version docs: https://crystal-lang.org/api/latest/

[will]

Something is going weird with the redirects @asterite @bcardiff @waj

~ ➤ curl -sLI https://crystal-lang.org/api/current | grep Location
Location: https://crystal-lang.org/api/latest/current
Location: https://crystal-lang.org/api/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/0.18.6/current

[asterite]

Yes, this is a known issue if you hit an unknown path, you'll get an error. But you'll get an error in any case for not found, 404 in this case. There's no way to correctly implement this with S3 buckets.

[bcardiff]

I finally get rid of them, not in the cleanest way.

$ curl -sLI https://crystal-lang.org/api/current | grep Location
Location: https://crystal-lang.org/api/latest/current
Location: https://crystal-lang.org/api/0.18.6/current
Location: https://crystal-lang.org/api/latest/0.18.6/current
Location: https://crystal-lang.org/404

Someday we could do a nice 404, but at least it stops the redirection loop. "Fixed" at https://github.com/crystal-lang/crystal/commit/2f157a6eb69ab109ddfebc0fcda6056ef6da32fa