grunt-wp-readme

    0.2.0 • Public • Published

    grunt-wp-readme

    Generate a readme.txt for your WordPress plugins.

    Getting Started

    This plugin requires Grunt ~0.4.1

    If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

    npm install grunt-wp-readme --save-dev

    Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

    grunt.loadNpmTasks('grunt-wp-readme');

    The "wp_readme" task

    Overview

    In your project's Gruntfile, add a section named wp_readme to the data object passed into grunt.initConfig().

    grunt.initConfig({
      wp_readme: {
        options: {
          readme: 'readme.txt',
          defaultInstallation: '',
          defaultFaq: '',
          defaultChangelog: '',
          defaultUpgrade: '',
          defaultScreenshots: ''
        },
        your_target: {
          displayName: '',
          contributors: [],
          donateLink: '',
          tags: [],
          minimumVersion: '',
          testedUpTo: '',
          stableTag: '',
          license: 'GPL-2.0+',
          licenseURI: 'http://www.gnu.org/licenses/gpl-2.0.html',
          textDomain: '',
          domainPath: '',
          blurb: '',
          sections: {
            description: '',
            installation: '',
            faq: [],
            screenshots: [],
            changelog: [],
            upgrade: '',
            extra: {header: false, body: false}
          }
        },
      },
    });

    Options

    readme

    Type: String

    You can specify a custom location for the readme.txt file to be saved. By default, it will be saved to readme.txt in the same directory as your Gruntfile.js file. If the value you set for readme doesn't end with readme.txt, it is assumed to be a directory and will append /readme.txt to the value.

    defaultInstallation

    Type: String

    The default value of the Installation section if it is left undefined in your configuration

    defaultFaq

    Type: String

    The default value of the FAQ section if left undefined

    defaultChangelog

    Type: String

    The default value of the Changelog section if left undefined

    defaultUpgrade

    Type: String

    The default value of the Upgrade Notice section if left undefined

    defaultScreenshots

    Type: String

    The default value of the Screenshots

    Configuration

    displayName

    Type: String REQUIRED

    Your plugin's display name

    contributors

    Type: Array REQUIRED

    An array of wordpress.org usernames. At least one must be specified.

    donateLink

    Type: Array

    Optional URL for donations

    tags

    Type: Array

    An array of tags to help people find your plugin

    minimumVersion

    Type: String REQUIRED

    The minimum supported version of WordPress that your plugin works with

    testedUpTo

    Type: String REQUIRED

    The version of WordPress up to which you've verified that your plugin works

    stableTag

    Type: String REQUIRED

    The current stable version of your plugin.

    license

    Type: String

    License under which your plugin is distributed. Defaults to GPL 2.0+.

    licenseURI

    Type: String

    Link to license text. Defaults to http://www.gnu.org/licenses/gpl-2.0.html

    textDomain

    Type: String

    The textdomain of the plugin for internationalization.

    domainPath

    Type: String

    The location of your translation files relative to the root directory of your plugin. If specified, it should have a leading slash.

    blurb

    Type: String

    A short (preferably one sentence) description of your plugin

    sections

    Type: Object

    An object detailing the contents of any sections of the plugin's readme.txt. See below for more details on sections and their structure/format.

    Sections

    description

    Type: String

    Longer description of plugin. Defaults to the value set in blurb.

    installation

    Type: String|Array

    String or array of strings detailing installation instructions. If an array of strings is provided, they will be turned into an ordered list.

    faq

    Type: Array

    Array of faq objects. Faq objects must have a question and answer property. For example:

    faq: [
      {
        question: 'What is this?',
        answer: 'This is a FAQ sections!'
      },
      {
        question: 'Do people really ask this with any degree of frequency?',
        answer: 'No... :('
      }
    ]

    screenshots

    Type: Array

    Array of screenshot captions. They will be added in the order in which they are given.

    changelog

    Type: Array

    Array of changelog objects. changelog objects have the following properties:

    • version Required Type: String. The version of the release being described
    • changes Required Type: Array. An array of changes made in this version. Will be turned into an unordered list.
    • releaseDate Optional Type: String. An optional date of release for the current version. If provided, it will be prepended to the unordered list of changes in this format: Released: {{date}}. The format of the date doesn't really matter. It's just a string.

    For example:

    changelog: [
      {
        version: '1.0.1',
        changes: [
          'Fixed a fatal error caused by using the plugin',
          'Started using grunt-wp-readme. ZOMG'
        ],
        releaseDate: '1/17/2014'
      },
      {
        version: '1.0',
        changes: ['Initial release.'],
        releaseDate: '2014-01-13'
      }
    ]

    upgrade

    Type: String

    Upgrade notice contents

    extra

    Type: Object

    If your plugin has an extra arbitrary section of the readme, you can define the header and body of it here, using an object with a header and body property.

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

    Release History

    0.1.0

    • Initial release

    Keywords

    Install

    npm i grunt-wp-readme

    DownloadsWeekly Downloads

    0

    Version

    0.2.0

    License

    none

    Last publish

    Collaborators

    • johnpbloch