kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

(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
This commit is contained in:
Eric Putnam 2018-04-25 09:06:42 +01:00
parent d4e743dbad
commit 8bfcdffbaa
No known key found for this signature in database
GPG Key ID: 3FB595AA224A7751
4 changed files with 153 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
CONTRIBUTING.md
View File

@ -1,6 +1,6 @@
# How to contribute # 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 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 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. 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. * Push your changes to a topic branch in your fork of the repository.
* Submit a pull request to the repository in the puppetlabs organization. * 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). * 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. * 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.
* After feedback has been given we expect responses within two weeks. After two * 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. weeks will may close the pull request if it isn't showing any activity.
# Additional Resources # Additional Resources
* [More information on contributing](http://links.puppet.com/contribute-to-puppet) * [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) * [Contributor License Agreement](http://links.puppet.com/cla)
* [General GitHub documentation](http://help.github.com/) * [General GitHub documentation](http://help.github.com/)
* [GitHub pull request documentation](http://help.github.com/send-pull-requests/) * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
* #puppet-dev IRC channel on freenode.org

134
JSON.md
View File

@ -1,15 +1,15 @@
Puppet Strings JSON Data Puppet Strings JSON Data
======================== ========================
Puppet Strings has two flags to the `generate` action that can be used to emit JSON data: Puppet Strings can generate JSON to STDOUT with the `--format` option:
```shell
* `--emit-json <file>`: Emits the JSON data to the given file. puppet strings generate --format json
* `--emit-json-stdout`: Emits the JSON data to STDOUT. ```
Document Schema 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 | | 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. | | defined_types | The list of defined types that were parsed. |
| resource_types | The list of resource types that were parsed. | | resource_types | The list of resource types that were parsed. |
| providers | The list of resource providers 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 Puppet Classes
-------------- --------------
@ -117,14 +119,43 @@ Each entry in the `puppet_functions` list is an object with the following attrib
| Attribute Key | Description | | Attribute Key | Description |
| ------------- | ----------------------------------------------------------------------------- | | ------------- | ----------------------------------------------------------------------------- |
| name | The name of the function. | | name | The name of the function. |
| file | The file defining the provider. | | file | The file defining the function. |
| line | The line where the provider is defined. | | line | The line where the function is defined. |
| type | The function type (e.g. ruby3x, ruby4x, puppet). | | type | The function type (e.g. ruby3x, ruby4x, puppet). |
| signatures | A list of Puppet signatures of the function, including overloads if present. | | signatures | A list of Puppet signatures of the function, including overloads if present. |
| docstring | The *DocString* object for the function (see below). | | docstring | The *DocString* object for the function (see below). |
| defaults | The map of parameter names to default values. | | defaults | The map of parameter names to default values. |
| source | The source code for the function. | | 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 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" "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}"
}
] ]
} }
``` ```

17
MAINTAINERS
View File

@ -1,17 +0,0 @@
{
"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"
}
]
}

28
README.md
View File

@ -157,7 +157,7 @@ Action | Description
### `puppet strings generate` command reference ### `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: For example:
@ -169,8 +169,6 @@ puppet strings generate --format markdown --out docs/info.md
puppet strings generate manifest1.pp manifest2.pp puppet strings generate manifest1.pp manifest2.pp
``` ```
[--format <OUTPUT_FORMAT>][--out <DESTINATION_PATH> [<ARGUMENTS>]
Option | Description | Values | Default Option | Description | Values | Default
----------------|:---------------:|:------------------:|------------------------- ----------------|:---------------:|:------------------:|-------------------------
`--format` | Specifies a format for documentation. | markdown, json | If not specified, Strings outputs HTML documentation. `--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. `--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. `--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. `--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 # Puppet Strings style