(maint) update various documentation

This updates various docs in the project.
* Get rid of MAINTAINERS
* Update JSON.md with tasks and plans
* Fix some weirndess in the README
* Polish CONTRIBUTING.md
parent d4e743db
# How to contribute
Third-party patches are essential for keeping strings great. We want to keep it
Third-party patches are essential for keeping Puppet Strings great. We want to keep it
as easy as possible to contribute changes that get things working in your
environment. There are a few guidelines that we need contributors to follow so
that we can have a chance of keeping on top of things.
......@@ -72,18 +72,14 @@ a ticket number.
* Push your changes to a topic branch in your fork of the repository.
* Submit a pull request to the repository in the puppetlabs organization.
* Update your Jira ticket to mark that you have submitted code and are ready for it to be reviewed (Status: Ready for Merge).
* Include a link to the pull request in the ticket.
* The core team looks at Pull Requests on a regular basis in a weekly triage
meeting that we hold in a public Google Hangout. The hangout is announced in
the weekly status updates that are sent to the puppet-dev list.
* Include a link to the pull request in the ticket.
* After feedback has been given we expect responses within two weeks. After two
weeks will may close the pull request if it isn't showing any activity.
# Additional Resources
* [More information on contributing](http://links.puppet.com/contribute-to-puppet)
* [Bug tracker (Jira)](http://tickets.puppetlabs.com)
* [Bug tracker (Jira)](http://tickets.puppet.com)
* [Contributor License Agreement](http://links.puppet.com/cla)
* [General GitHub documentation](http://help.github.com/)
* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
* #puppet-dev IRC channel on freenode.org
Puppet Strings JSON Data
========================
Puppet Strings has two flags to the `generate` action that can be used to emit JSON data:
* `--emit-json <file>`: Emits the JSON data to the given file.
* `--emit-json-stdout`: Emits the JSON data to STDOUT.
Puppet Strings can generate JSON to STDOUT with the `--format` option:
```shell
puppet strings generate --format json
```
Document Schema
===============
At the top level, there are five arrays in the JSON document:
At the top level, there are seven arrays in the JSON document:
| Document Key | Description |
| ---------------- | ----------------------------------------------------------------------------- |
......@@ -17,7 +17,9 @@ At the top level, there are five arrays in the JSON document:
| defined_types | The list of defined types that were parsed. |
| resource_types | The list of resource types that were parsed. |
| providers | The list of resource providers that were parsed. |
| puppet_functions | The list of Puppet functions (3.x, 4.x and Puppet language) that were parsed. |
| puppet_functions | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. |
| puppet_tasks | The list of Puppet tasks that were parsed. |
| puppet_plans | The list of Puppet plans that were parsed. |
Puppet Classes
--------------
......@@ -117,14 +119,43 @@ Each entry in the `puppet_functions` list is an object with the following attrib
| Attribute Key | Description |
| ------------- | ----------------------------------------------------------------------------- |
| name | The name of the function. |
| file | The file defining the provider. |
| line | The line where the provider is defined. |
| file | The file defining the function. |
| line | The line where the function is defined. |
| type | The function type (e.g. ruby3x, ruby4x, puppet). |
| signatures | A list of Puppet signatures of the function, including overloads if present. |
| docstring | The *DocString* object for the function (see below). |
| defaults | The map of parameter names to default values. |
| source | The source code for the function. |
Puppet Tasks
------------
Each entry in the `puppet_tasks` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ----------------------------------------------------------------------------- |
| name | The name of the task. |
| file | The file defining the task. |
| line | The line where the task is defined. |
| docstring | The *DocString* object for the task (see below). |
| source | The source code for the task. |
| supports_noop | Whether the task supports noop mode |
| input_method | Maps to the `input_method` key in the task json |
Puppet Plans
------------
Each entry in the `puppet_plans` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ----------------------------------------------------------------------------- |
| name | The name of the plan. |
| file | The file defining the plan. |
| line | The line where the plan is defined. |
| docstring | The *DocString* object for the plan (see below). |
| defaults | The map of parameter names to default values. |
| source | The source code for the plan. |
Signature Objects
-----------------
......@@ -679,6 +710,93 @@ An example JSON document describing a Puppet class, defined type, resource type,
},
"source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return [Undef] Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n end\n\n # The second overload.\n # @param param The first parameter.\n # @param block The block parameter.\n # @return [String] Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n end\nend"
}
],
"puppet_tasks": [
{
"name": "(stdin)",
"file": "(stdin)",
"line": 0,
"docstring": {
"text": "Allows you to backup your database to local file.",
"tags": [
{
"name": "database",
"tag_name": "param",
"text": "Database to connect to",
"types": [
"Optional[String[1]]"
]
},
{
"name": "user",
"tag_name": "param",
"text": "The user",
"types": [
"Optional[String[1]]"
]
},
{
"name": "password",
"tag_name": "param",
"text": "The password",
"types": [
"Optional[String[1]]"
]
},
{
"name": "sql",
"tag_name": "param",
"text": "Path to file you want backup to",
"types": [
"String[1]"
]
}
]
},
"source": "{\n \"description\": \"Allows you to backup your database to local file.\",\n \"input_method\": \"stdin\",\n \"parameters\": {\n \"database\": {\n \"description\": \"Database to connect to\",\n \"type\": \"Optional[String[1]]\"\n },\n \"user\": {\n \"description\": \"The user\",\n \"type\": \"Optional[String[1]]\"\n },\n \"password\": {\n \"description\": \"The password\",\n \"type\": \"Optional[String[1]]\"\n },\n \"sql\": {\n \"description\": \"Path to file you want backup to\",\n \"type\": \"String[1]\"\n }\n }\n}\n",
"supports_noop": false,
"input_method": "stdin"
}
],
"puppet_plans": [
{
"name": "plann",
"file": "(stdin)",
"line": 5,
"docstring": {
"text": "A simple plan.",
"tags": [
{
"tag_name": "param",
"text": "First param.",
"types": [
"String"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "Second param.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "Third param.",
"types": [
"Integer"
],
"name": "param3"
}
]
},
"defaults": {
"param3": "1"
},
"source": "plan plann(String $param1, $param2, Integer $param3 = 1) {\n}"
}
]
}
```
{
"version": 1,
"file_format": "This MAINTAINERS file format is described at http://pup.pt/maintainers",
"issues": "https://tickets.puppetlabs.com/browse/PDOC",
"people": [
{
"github": "whopper",
"email": "whopper@puppet.com",
"name": "Will Hopper"
},
{
"github": "scotje",
"email": "jesse@puppet.com",
"name": "Jesse Scott"
}
]
}
......@@ -157,7 +157,7 @@ Action | Description
### `puppet strings generate` command reference
Usage: `puppet strings [generate] [--format <FORMAT>][--out <DESTINATION>] [<ARGUMENTS>]
Usage: `puppet strings generate [--format <FORMAT>][--out <DESTINATION>] [<ARGUMENTS>]`
For example:
......@@ -169,8 +169,6 @@ puppet strings generate --format markdown --out docs/info.md
puppet strings generate manifest1.pp manifest2.pp
```
[--format <OUTPUT_FORMAT>][--out <DESTINATION_PATH> [<ARGUMENTS>]
Option | Description | Values | Default
----------------|:---------------:|:------------------:|-------------------------
`--format` | Specifies a format for documentation. | markdown, json | If not specified, Strings outputs HTML documentation.
......@@ -179,7 +177,29 @@ Filenames or directory paths | Outputs documentation for only specified files or
`--verbose` | Logs verbosely. | none | If not specified, Strings logs basic information.
`--debug` | Logs debug information. | none | If not specified, Strings does not log debug information.
`--markup FORMAT` | The markup format to use for docstring text | "markdown", "textile", "rdoc", "ruby", "text", "html", or "none" | By default, Strings outputs HTML, if no `--format` is specified or Markdown if `--format markdown` is specified.
`--help` | Displays help documentation for the command. | Markdown, JSON | If not specified, Strings outputs HTML documentation.
`--help` | Displays help documentation for the command. | none | If not specified, Strings outputs HTML documentation.
### `puppet strings server` command reference
Usage: `puppet strings server [--markup <FORMAT>][[module_name]...][--modulepath <PATH]`
For example:
```
puppet strings server --modulepath path/to/modules
```
```
puppet strings server concat
```
Option | Description | Values | Default
----------------|:---------------:|:------------------:|-------------------------
`--modulepath` | Puppet option for setting the module path | Valid path | Defaults to Puppet's current module path
`--verbose` | Logs verbosely. | none | If not specified, Strings logs basic information.
`--debug` | Logs debug information. | none | If not specified, Strings does not log debug information.
`--markup FORMAT` | The markup format to use for docstring text | "markdown", "textile", "rdoc", "ruby", "text", "html", or "none" | By default, Strings outputs HTML, if no `--format` is specified or Markdown if `--format markdown` is specified.
`--help` | Displays help documentation for the command. | none | If not specified, Strings outputs HTML documentation.
# Puppet Strings style
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment