From 60bd7a69a70ba53106009556cfdbf4fd0c66ea4d Mon Sep 17 00:00:00 2001 From: chris48s Date: Mon, 9 Sep 2019 21:37:43 +0100 Subject: [PATCH] link to contributing.shields.io in the docs (#3957) * link to shields-docs.netlify.com in the docs * update links to contributing.shields.io --- CONTRIBUTING.md | 10 ++++++++++ doc/TUTORIAL.md | 26 ++++++++++++++------------ doc/production-hosting.md | 1 + 3 files changed, 25 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddfb373327..e1014e48c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,10 +24,20 @@ maybe you'd like to open a pull request to address one of them: You can help by improving the project's usage and developer instructions. +Tutorials are in [/doc](https://github.com/badges/shields/tree/master/doc): + - When you read the documentation, you can fix mistakes and add your own thoughts. - When your pull request follows the documentation but the practice changed, consider pointing this out and change the documentation for the next person. +API documentation is at [contributing.shields.io](https://contributing.shields.io/): + +- This documentation is generated by annotating the code with + [JSDoc](https://jsdoc.app/about-getting-started.html) comments. + [Example](https://github.com/badges/shields/blob/b3be4d94d5ef570b8daccfd088c343a958988843/core/base-service/base-json.js#L26-L41) +- Adding a JSDoc comment to some existing code is a great first contribution + and a good way to familiarize yourself with the codebase + ### Helping others You can help with code review, which reduces bugs, and over time has a diff --git a/doc/TUTORIAL.md b/doc/TUTORIAL.md index ad160dba4b..bebe931170 100644 --- a/doc/TUTORIAL.md +++ b/doc/TUTORIAL.md @@ -7,11 +7,11 @@ Please [improve the tutorial](https://github.com/badges/shields/edit/master/doc/ ## (1) Reading -You should read [CONTRIBUTING.md](../CONTRIBUTING.md) - -You can also read previous -[merged pull-requests with the 'service-badge' label](https://github.com/badges/shields/pulls?utf8=%E2%9C%93&q=is%3Apr+label%3Aservice-badge+is%3Amerged) -to see how other people implemented their badges. +- [Contributing Guidance](../CONTRIBUTING.md) +- [Documentation](https://contributing.shields.io/index.html) for the Shields Core API +- You can also read previous + [merged pull-requests with the 'service-badge' label](https://github.com/badges/shields/pulls?utf8=%E2%9C%93&q=is%3Apr+label%3Aservice-badge+is%3Amerged) + to see how other people implemented their badges. ## (2) Setup @@ -90,18 +90,20 @@ Each service has a directory for its files: All service badge classes inherit from [BaseService] or another class which extends it. Other classes implement useful behavior on top of [BaseService]. -- [BaseJsonService](https://github.com/badges/shields/blob/master/core/base-service/base-json.js) +- [BaseJsonService](https://contributing.shields.io/module-core_base-service_base-json-basejsonservice) implements methods for performing requests to a JSON API and schema validation. -- [BaseXmlService](https://github.com/badges/shields/blob/master/core/base-service/base-xml.js) +- [BaseXmlService](https://contributing.shields.io/module-core_base-service_base-xml-basexmlservice) implements methods for performing requests to an XML API and schema validation. -- [BaseYamlService](https://github.com/badges/shields/blob/master/core/base-service/base-yaml.js) +- [BaseYamlService](https://contributing.shields.io/module-core_base-service_base-yaml-baseyamlservice) implements methods for performing requests to a YAML API and schema validation. -- [BaseSvgScrapingService](https://github.com/badges/shields/blob/master/core/base-service/base-svg-scraping.js) +- [BaseSvgScrapingService](https://contributing.shields.io/module-core_base-service_base-svg-scraping-basesvgscrapingservice) implements methods for retrieving information from existing third-party badges. +- [BaseGraphqlService](https://contributing.shields.io/module-core_base-service_base-graphql-basegraphqlservice) + implements methods for performing requests to a GraphQL API and schema validation. - If you are contributing to a _service family_, you may define a common super class for the badges or one may already exist. -[baseservice]: https://github.com/badges/shields/blob/master/core/base-service/base.js +[baseservice]: https://contributing.shields.io/module-core_base-service_base-baseservice As a first step we will look at the code for an example which generates a badge without contacting an API. @@ -277,8 +279,8 @@ Specifically `BaseJsonService` will handle the following errors for us: - API returns a response which doesn't validate against our schema Sometimes it may be necessary to manually throw an exception to deal with a -non-standard error condition. If so, there are several standard exceptions that can be used. These exceptions are defined in -[errors.js](https://github.com/badges/shields/blob/master/core/base-service/errors.js) +non-standard error condition. If so, there are several standard exceptions that can be used. The errors are documented at +[errors](https://contributing.shields.io/module-core_base-service_errors.html) and can be imported via the import shortcut and then thrown: ```js diff --git a/doc/production-hosting.md b/doc/production-hosting.md index 7b64fcb91e..985c914e95 100644 --- a/doc/production-hosting.md +++ b/doc/production-hosting.md @@ -30,6 +30,7 @@ | Metrics server | Owner | @platan | | UptimeRobot | Account owner | @paulmelnikow | | More metrics | Owner | @RedSparr0w | +| Netlify (documentation site) | Owner | @chris48s | There are [too many bottlenecks][issue 2577]!