Crystal: Specify folder name for generated documentation

[vladfaust]

GitHub Pages allow to configure source. It can be either master or master/docs. It would be convenient if a developer could pass a folder name to crystal docs like crystal docs -f docs.

Or maybe even change the default folder name to docs. Plural form is more familiar to me as a developer. Nobody says "read the doc", they usually say "read the docs".

[vladfaust]

Managed to automatically deploy to gh-pages after Travis build: travis.yml.

But still think that docs is a better name.

[RX14]

This might still be something we want to implement.

[straight-shoota]

I'd also prefer docs as default folder. Though it's debatable, I doubt that one is really preferable over the other.
Judging from a few examples what other projects are using the plural seems a bit more common. But in the end it probably won't matter much.
I'd just argue that the command is called crystal docs so it would be neat to create a folder called docs.

It should definitely be possible to configure the output directory. Some projects might want to use the docs/doc folder for handwritten documentation and put the autogenerated API docs into apidocs for example. Or an entirely different location, e.g. for automatic deployment to the docs site.

[asterite]

Let's change it to docs

[asterite]

But also let's add an option to configure it. But if docs is more common (and I think it is), let's change both things.

[bcardiff]

People interested in publishing docs as gh-pages might like checking https://github.com/bcardiff/ghshard .

Publishing docs is more than publishing just the master. The other stories around docs I remember where hooking some artifact to allow redirections to last current stable version (and highlight outdated one) and changing the index document from README.md to DOCS.md or something more appropriate for docs than repos.

It might be useful to have this other scenarios into account to decide if the options should be as command line arguments or maybe in shards.yml o some other configuration file. I'm ok if all is configurable via command line arguments though.

[straight-shoota]

I am using a bash script for automatically generating and deploying API documentation through CI (or manually): autodeploy-docs. It is not limited to Crystal documentation, though also not that deeply integrated with shards but uses git tags.