From ccb533fae93ca6c50089eea4275fd5c71fa007b3 Mon Sep 17 00:00:00 2001 From: Josh Smith Date: Sun, 27 Nov 2016 15:49:02 -0800 Subject: [PATCH] Improve docs --- .github/CONTRIBUTING.md | 2 +- LICENSE.txt => LICENSE.md | 0 README.md | 30 +++++++++++++++--------------- docs/USAGE.md => USAGE.md | 0 mix.exs | 12 ++++++++++++ 5 files changed, 28 insertions(+), 16 deletions(-) rename LICENSE.txt => LICENSE.md (100%) rename docs/USAGE.md => USAGE.md (100%) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 8d4464565..1e9956252 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -204,4 +204,4 @@ Some tests are tagged like so: These tests do not run by default when running `mix test` because you do not have access to the environment variables listed in `.env.example` by default. -To read more about the environment variables, see the "Environment" section of our [usage docs](docs/USAGE.md#environment). +To read more about the environment variables, see the "Environment" section of our [usage docs](USAGE.md#environment). diff --git a/LICENSE.txt b/LICENSE.md similarity index 100% rename from LICENSE.txt rename to LICENSE.md diff --git a/README.md b/README.md index 134b27cb9..15034c39c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Code Corps Elixir API +# Code Corps API ![Code Corps Phoenix Logo](https://d3pgew4wbk2vb1.cloudfront.net/images/github/code-corps-api.png) @@ -19,41 +19,41 @@ Our goals: We'd love to have you contribute to Code Corps directly! -- First, read the guidelines in our [`CONTRIBUTING.md`](.github/CONTRIBUTING.md). +- First, read the guidelines in our [`CONTRIBUTING.md`](https://github.com/code-corps/code-corps-api/blob/develop/.github/CONTRIBUTING.md). - Then check out some GitHub issues to see where you can help out. You can also always come :wave: hello [in our Slack](http://slack.codecorps.org), where there are always a ton of us around to help you learn, debug, or just shoot the breeze. We highlight everyone who's contributed to [the Code Corps team page](https://www.codecorps.org/team). If we've missed you for some reason, please [open an issue in the Ember app](https://github.com/code-corps/code-corps-ember/issues/new)! -**At the moment, our focus is integration with Stripe**, so if you want to help, that would be the most useful spot. Check our [Donations milestone](https://github.com/code-corps/code-corps-api/milestone/1) to see which parts we need help on. Of course, help with other areas is always welcome, so if that sort of thing isn't your cup of tea, feel free to pick anything else. +**At the moment, our focus is integration with Stripe**, so if you want to help, that would be the most useful spot. Check our [Donations milestone](https://github.com/code-corps/code-corps-api/blob/develop/milestone/1) to see which parts we need help on. Of course, help with other areas is always welcome, so if that sort of thing isn't your cup of tea, feel free to pick anything else. ## Installing with Docker -To make your life easier, you can just clone this repository and use our Docker container. [Follow this guide to get started.](docs/INSTALLING.md) +To make your life easier, you can just clone this repository and use our Docker container. [Follow this guide to get started.](https://github.com/code-corps/code-corps-api/blob/develop/docs/INSTALLING.md) ## Usage -Have everything installed and ready to work? Read [our usage guides](docs/USAGE.md) to learn how to: +Have everything installed and ready to work? Read [our usage guides](USAGE.md) to learn how to: -- [Run normal `mix` commands through Docker](docs/USAGE.md#interacting-with-the-app) -- [Stop and start the server](docs/USAGE.md#stopping-and-starting-the-server) -- [Run tests](docs/USAGE.md#running-tests) -- [Linting and Style Guidelines](docs/USAGE.md#linting-code-with-credo) -- [Rebuild Docker containers](docs/USAGE.md#rebuilding-docker-containers) -- [Work with the Ember front-end](docs/USAGE.md#serving-ember) -- [Set up environment variables](docs/USAGE.md#environment) -- [Push changes to GitHub](docs/USAGE.md#pushing-changes) +- [Run normal `mix` commands through Docker](USAGE.md#interacting-with-the-app) +- [Stop and start the server](USAGE.md#stopping-and-starting-the-server) +- [Run tests](USAGE.md#running-tests) +- [Linting and Style Guidelines](USAGE.md#linting-code-with-credo) +- [Rebuild Docker containers](USAGE.md#rebuilding-docker-containers) +- [Work with the Ember front-end](USAGE.md#serving-ember) +- [Set up environment variables](USAGE.md#environment) +- [Push changes to GitHub](USAGE.md#pushing-changes) ## Documentation We have several types of docs: - Project documentation (README, CONTRIBUTING, etc.) -- [API documentation](http://docs.codecorpsapi.apiary.io/) written in [API Blueprint](https://apiblueprint.org/) format in [`blueprint/api.apib`](blueprint/api.apib) and published to the web when merging into `develop` +- [API documentation](http://docs.codecorpsapi.apiary.io/) written in [API Blueprint](https://apiblueprint.org/) format in [`blueprint/api.apib`](https://github.com/code-corps/code-corps-api/blob/develop/blueprint/api.apib) and published to the web when merging into `develop` - [Inline documentation](https://code-corps.github.io/code-corps-api-github-pages) for the Elixir app generated by [`ex_doc`](https://github.com/elixir-lang/ex_doc) and published to GitHub pages when merging into `develop` -Want to improve the documentation? [Get started here.](.github/CONTRIBUTING.md#what-kind-of-documentation-are-you-writing) +Want to improve the documentation? [Get started here.](https://github.com/code-corps/code-corps-api/blob/develop/.github/CONTRIBUTING.md#what-kind-of-documentation-are-you-writing) ## Things we care about diff --git a/docs/USAGE.md b/USAGE.md similarity index 100% rename from docs/USAGE.md rename to USAGE.md diff --git a/mix.exs b/mix.exs index 113bba9a8..2ad2c555f 100644 --- a/mix.exs +++ b/mix.exs @@ -11,6 +11,7 @@ defmodule CodeCorps.Mixfile do start_permanent: Mix.env == :prod, aliases: aliases(), deps: deps(), + docs: docs(), test_coverage: [tool: ExCoveralls]] end @@ -91,6 +92,17 @@ defmodule CodeCorps.Mixfile do ] end + defp docs do + [ + extras: [ + "README.md": [title: "README"], + "LICENSE.md": [title: "LICENSE"] + ], + main: "README", + source_url: "https://github.com/code-corps/code-corps-api/doc" + ] + end + # Aliases are shortcuts or tasks specific to the current project. # For example, to create, migrate and run the seeds file at once: #