From 65eea1b82f3b55560831c27aabcb64c761fe0854 Mon Sep 17 00:00:00 2001 From: Jake Bolam Date: Wed, 23 Jan 2019 17:05:33 -0500 Subject: [PATCH] docs: centralize docs on website (#153) * docs: centralize docs on website * Update README.md * Update README.md --- README.md | 191 +----------------------------------------------------- 1 file changed, 2 insertions(+), 189 deletions(-) diff --git a/README.md b/README.md index 43ce12a..2767421 100644 --- a/README.md +++ b/README.md @@ -32,195 +32,9 @@ This is a tool to help automate adding contributor acknowledgements according to the [all-contributors](https://github.com/all-contributors/all-contributors) specification for your GitHub or GitLab repository. -## Table of Contents +## Using the all-contributors-cli - - - -- [Installation](#installation) -- [Usage](#usage) - - [Generating the contributors list](#generating-the-contributors-list) - - [Add/update contributors](#addupdate-contributors) - - [Check for missing contributors](#check-for-missing-contributors) -- [Configuration](#configuration) -- [Contributors](#contributors) -- [LICENSE](#license) - - - -## Installation - -This module is distributed via [npm][npm] which is bundled with [node][node] and -should be installed as one of your project's `devDependencies`: - -``` -npm install --save-dev all-contributors-cli -``` - -Then init the project using `init` and answer a few questions: - -```console -# Use npx for npm@^5.2.0 -npx all-contributors init -# Or directly execute the bin -./node_modules/.bin/all-contributors init -``` - -Then you can add these scripts to your `package.json`: - -```json -{ - "scripts": { - "contributors:add": "all-contributors add", - "contributors:generate": "all-contributors generate" - } -} -``` - -and use them via `npm run`: - -```console -npm run contributors:add -- jfmengels doc -npm run contributors:generate -``` - -## Usage - -A quick note: We recommend that you install `all-contributors-cli` as a dependency in your project. -If you do that then you can run the `all-contributors` binary from within your `package.json` scripts, or you can run it in your terminal with `npx all-contributors`. -Below we'll just show `all-contributors` to keep things simple, but if you're having any difficulties, then give the `npx all-contributors-cli` route a try :smiley_cat: - -### Generating the contributors list - -Please add following placeholders in [`files`](#configuration) to specify the generation area first. - -
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-
- -Then use `generate` to generate the contributors list and inject it into your -contributors file. Contributors will be read from your configuration file. - -```console -all-contributors generate -``` - -### Add/update contributors - -Use `add` to add new contributors to your project, or add new ways in which they -have contributed. They will be added to your configuration file, and the -contributors file will be updated just as if you used the `generate` command. - -```console -# Add new contributor , who made a contribution of type -all-contributors add -# Example: -all-contributors add jfmengels code,doc -``` - -Where `username` is the user's GitHub or Gitlab username, and `contribution` is a -`,`-separated list of ways to contribute, from the following list -([see the specs](https://github.com/all-contributors/all-contributors#emoji-key)): - -- blog: [📝](# 'Blogposts') -- bug: [🐛](# 'Bug reports') -- code: [💻](# 'Code') -- design: [🎨](# 'Design') -- doc: [📖](# 'Documentation') -- eventOrganizing: [📋](# 'Event Organizing') -- example: [💡](# 'Examples') -- financial: [💵](# 'Financial') -- fundingFinding: [🔍](# 'Funding Finding') -- ideas: [🤔](# 'Ideas, Planning, & Feedback') -- infra: [🚇](# 'Infrastructure (Hosting, Build-Tools, etc)') -- maintenance [🚧](# 'Maintenance') -- platform: [📦](# 'Packaging/porting to new platform') -- plugin: [🔌](# 'Plugin/utility libraries') -- question: [💬](# 'Answering Questions') -- review: [👀](# 'Reviewed Pull Requests') -- security: [🛡](# 'Security') -- talk: [📢](# 'Talks') -- test: [⚠️](# 'Tests') -- tool: [🔧](# 'Tools') -- translation: [🌍](# 'Translation') -- tutorial: [✅](# 'Tutorials') -- userTesting: [📓](# 'User Testing') -- video: [📹](# 'Videos') - -Please note that if you are using a self-hosted gitlab instance, before adding -contributor, you need to set an environment variable named `PRIVATE_TOKEN` first. - -> Private token is the personal access token to authenticate with the GitLab API. - -```console -# set private token on linux -export PRIVATE_TOKEN=your_private_token -# set private token on windows -set PRIVATE_TOKEN=your_private_token -``` - -### Check for missing contributors - -Use `check` to compare contributors from GitHub with the ones credited in your -`.all-contributorsrc` file, in order to make sure that credit is given where -it's due. - -```console -all-contributors check -``` - -> Due to GitHub API restrictions, this command only works for projects with less -> than 500 contributors. (Unless you set a PRIVATE_TOKEN) as mentioned below - -## Configuration - -You can configure the project by updating the `.all-contributorsrc` JSON file. -The data used to generate the contributors list will be stored in there, and you -can configure how you want `all-contributors-cli` to generate the list. - -These are the keys you can specify: - -| Option | Description | Example/Default | -| --------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `projectName` | Mandatory, name of the project. | Example: `all-contributors-cli` | -| `projectOwner` | Mandatory, name of the user the project is hosted by. | Example: `jfmengels` | -| `repoType` | Type of repository. Must be either `github` or `gitlab`. | Default: `github` | -| `repoHost` | Points to the repository hostname. Change it if you use a self-hosted repository. | Default: `https://github.com` if `repoType` is `github`, and `https://gitlab.com` if `repoType` is `gitlab` | -| `files` | Array of files to update. | Default: `['README.md']` | -| `imageSize` | Size (in px) of the user's avatar. | Default: `100` | -| `commit` | Auto-commit badge when adding contributors. | `true` or `false` | -| `contributorsPerLine` | Maximum number of columns for the contributors table. | Default: `7` | -| `badgeTemplate` | Define your own lodash template to generate the badge. | -| `contributorTemplate` | Define your own lodash template to generate the contributor. | -| `types` | Specify custom symbols or link templates for contribution types. Can override the documented types. | - -```json -{ - "projectName": "all-contributors-cli", - "projectOwner": "jfmengels", - "repoType": "github", - "repoHost": "https://github.com", - "files": ["README.md"], - "imageSize": 100, - "commit": false, - "contributorsPerLine": 7, - "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg?style=flat-square)](#contributors)", - "contributorTemplate": "<%= avatarBlock %>
<%= contributions %>", - "types": { - "custom": { - "symbol": "🔭", - "description": "A custom contribution type.", - "link": "[<%= symbol %>](<%= url %> \"<%= description %>\")," - } - }, - "contributors": [] -} -``` - -In some cases you may see the error message 'GitHub API rate limit exceeded for xxx'. You may need to set an environment variable named `PRIVATE_TOKEN` in order to circumvent this [GitHub rate limit](https://developer.github.com/v3/rate_limit/). - -> Private token is your personal access token to authenticate with the GitHub API. +If you're looking to use the cli, head over to [the cli docs on all-contributors.js.org](https://all-contributors.js.org/docs/cli/overview). The all-contributors website contains all the information required to install, configure and use the all-contributors-cli. ## Contributors @@ -241,7 +55,6 @@ Thanks goes to these wonderful people This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome! -We are also [looking for maintainers](https://github.com/all-contributors/all-contributors-cli/issues/129) ## LICENSE