Hosting on GitHub¶
- Create a repository with the same
descriptionas specified in your
Add and commit everything:
$ git add -A && git commit -am "shard complete"
Add the remote: (Be sure to replace
!!!note If you like, feel free to replace
origin, or a remote name of your choosing.
$ git remote add public https://github.com/<YOUR-GITHUB-NAME>/<YOUR-REPOSITORY-NAME>.git
$ git push public master
It's good practice to do GitHub Releases.
Add the following markdown build badge below the description in your README to inform users what the most current release is:
(Be sure to replace
Start by navigating to your repository's releases page.
This can be found at
Click "Create a new release".
According to the Crystal Shards README,
When libraries are installed from Git repositories, the repository is expected to have version tags following a semver-like format, prefixed with a
v. Examples: v1.2.3, v2.0.0-rc1 or v2017.04.1
Accordingly, in the input that says
tag version, type
v0.1.0. Make sure this matches the
shard.yml. Title it
v0.1.0 and write a short description for the release.
Click "Publish release" and you're done!
You'll now notice that the GitHub Release badge has updated in your README.
Follow Semantic Versioning and create a new release every time your push new code to
GitHub Actions allows you to automatically test your project on every commit. Configure it according to the dedicated guide.
You can also add a build status badge below the description in your README.md.
Hosting your docs on GitHub Pages¶
As an extension of the GitHub Actions config, you can add the steps to build the API doc site and then upload them, correspondingly:
steps: - name: Build docs run: crystal docs - name: Deploy docs if: github.event_name == 'push' && github.ref == 'refs/heads/master' uses: ... with: ...
-- where the latter
... placeholder is any of the generic GitHub Actions to push a directory to the gh-pages branch. Some options are:
- JamesIves/github-pages-deploy-action [Search]
- crazy-max/ghaction-github-pages [Search]
- peaceiris/actions-gh-pages [Search]
- oprypin/push-to-gh-pages [Search]
This uses Crystal's built-in API doc generator to make a generic site based on your code and comments to the items in it.
Rather than just publishing the generated API docs, consider also making a full textual manual of your project, for a well-rounded introduction.
For one of the options for static site generation, mkdocs-material, there's a solution to tightly integrate API documentation into an overall documentation site: mkdocstrings-crystal. Consider it as an alternative to