From 8bfcdffbaa55e222abec13a11669492da788b82f Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Wed, 25 Apr 2018 09:06:42 +0100 Subject: [PATCH] (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 --- CONTRIBUTING.md | 10 ++-- JSON.md | 134 +++++++++++++++++++++++++++++++++++++++++++++--- MAINTAINERS | 17 ------ README.md | 28 ++++++++-- 4 files changed, 153 insertions(+), 36 deletions(-) delete mode 100644 MAINTAINERS diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f366645..74a2415 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # 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 diff --git a/JSON.md b/JSON.md index f88f7a3..66e35ba 100644 --- a/JSON.md +++ b/JSON.md @@ -1,15 +1,15 @@ Puppet Strings JSON Data ======================== -Puppet Strings has two flags to the `generate` action that can be used to emit JSON data: - -* `--emit-json `: 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}" + } ] } ``` diff --git a/MAINTAINERS b/MAINTAINERS deleted file mode 100644 index 50e7844..0000000 --- a/MAINTAINERS +++ /dev/null @@ -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" - } - ] -} diff --git a/README.md b/README.md index 9f19e59..f01eab0 100644 --- a/README.md +++ b/README.md @@ -157,7 +157,7 @@ Action | Description ### `puppet strings generate` command reference -Usage: `puppet strings [generate] [--format ][--out ] [] +Usage: `puppet strings generate [--format ][--out ] []` For example: @@ -169,8 +169,6 @@ puppet strings generate --format markdown --out docs/info.md puppet strings generate manifest1.pp manifest2.pp ``` -[--format ][--out [] - 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 ][[module_name]...][--modulepath