From d99debd4c26196869ea41bb9d6c7a503ce23fd0e Mon Sep 17 00:00:00 2001 From: ScriptAutomate Date: Thu, 8 Apr 2021 11:57:39 -0500 Subject: [PATCH 1/6] Adding guidance on HTML docs gen --- README.md | 24 ++++++++++++++++++++++-- docs/gettingstarted.md | 7 +++++++ 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 147b0e9..9cfbe7c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # kitchen-salt # + [![Gem Version](https://badge.fury.io/rb/kitchen-salt.svg)](https://badge.fury.io/rb/kitchen-salt) [![Gem Downloads](https://ruby-gem-downloads-badge.herokuapp.com/kitchen-salt?type=total&color=brightgreen)](https://rubygems.org/gems/kitchen-salt) [![Build Status](https://github.com/saltstack/kitchen-salt/workflows/Tests/badge.svg)](https://github.com/saltstack/kitchen-salt/actions) @@ -9,6 +10,25 @@ The provider works by generating a salt-minion config, creating pillars based on This provisioner is tested with kitchen-docker against CentOS, Ubuntu, and Debian. -## Documentation ## +## Installation and Setup ## + +You'll need the test-kitchen and kitchen-salt gem's installed in your system, along with kitchen-vagrant or some other suitable driver for test-kitchen. Please see the [gettingstarted documentation](docs/gettingstarted.md). + +## Provisioner Options ## + +More details on all the configuration options are in the [provisioner_options documentation](docs/provisioner_options.md). + +## Requirements ## + +You'll need a driver box that is supported by the SaltStack [bootstrap](https://github.com/saltstack/salt-bootstrap) system. + +## Continuous Integration and Testing ## + +PR's and other changes should validated using Github Actions, kitchen-docker, multiple state dependencies, the modified version of kitchen-salt and the latest version of test-kitchen. + +## Releasing ## - + # hack. work. test. + git add stuff + git commit -v + gem bump --release --tag diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md index 2465e6d..d446405 100644 --- a/docs/gettingstarted.md +++ b/docs/gettingstarted.md @@ -122,6 +122,13 @@ To specify only installing certain groups, use the `--with` and `--without` argu bundle install --with windows --without docker +## Generate and locally view docs ## + +To view the docs that were originally generated by this repository and hosted by Salt Project, the following should generate a local copy of the documentation. + + # Generate HTML documentation of kitchen-salt + bundle exec yard server docroot=html/ + ## Setup ## Now the `.kitchen.yml` file needs to be setup for running tests. The following sections should be copied into the {file:docs/example-kitchen.yml.md} file in the root of the directory for the `wordpress-formula` From 5ab65924e5df8f8dde634b41bfd679d7ac909b92 Mon Sep 17 00:00:00 2001 From: ScriptAutomate Date: Fri, 9 Apr 2021 15:18:38 -0500 Subject: [PATCH 2/6] Update rbenv directions; specify docs gen paths --- .gitignore | 3 +++ docs/gettingstarted.md | 35 +++++++++++++++++------------------ 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/.gitignore b/.gitignore index babd194..c99b0aa 100644 --- a/.gitignore +++ b/.gitignore @@ -41,3 +41,6 @@ html/ .idea_modules/ atlassian-ide-plugin.xml .vscode + +# rbenv +.ruby-version diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md index d446405..5715429 100644 --- a/docs/gettingstarted.md +++ b/docs/gettingstarted.md @@ -24,30 +24,19 @@ For Linux, there is an [installer script](https://github.com/rbenv/rbenv-install The following instructions will allow for a global install of rbenv. -1. Install the dependencies for building ruby - - centos - - sudo yum install -y openssl-devel readline-devel zlib-devel bzip2 gcc make git - - - ubuntu - - sudo apt update - sudo apt install -y libssl-dev libreadline-dev zlib1g-dev bzip2 gcc make git +1. Install the dependencies for building ruby, referencing the `ruby-build` [Suggested build environment](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment) documentation. 1. clone git repos and setup path - sudo git clone git://github.com/rbenv/rbenv.git /usr/local/rbenv - sudo mkdir /usr/local/rbenv/plugins - sudo git clone git://github.com/rbenv/ruby-build.git /usr/local/rbenv/plugins/ruby-build - sudo tee /etc/profile.d/rbenv.sh <<< 'export PATH="/usr/local/rbenv/plugins/ruby-build/bin:/usr/local/rbenv/bin:$PATH"' - sudo tee -a /etc/profile.d/rbenv.sh <<< 'source <(rbenv init -)' - - now the shell needs to be restarted so that the rbenv commands are in the path, and then `rbenv init -` adds the shims path to the PATH as well. + - [Basic GitHub Checkout/setup of rbenv](https://github.com/rbenv/rbenv#basic-github-checkout) + - [Installation of `ruby-build`](https://github.com/rbenv/ruby-build#installation) 1. Install ruby and set it as the version to use by default - rbenv install 2.6.3 - rbenv global 2.6.3 + rbenv install 2.6.7 + rbenv local 2.6.7 + # OPTIONAL: Set global default version + # rbenv global 2.6.7 If gemsets are needed, the [rbenv-gemset](https://github.com/jf/rbenv-gemset) plugin can be added to the gemsets repository. @@ -126,7 +115,17 @@ To specify only installing certain groups, use the `--with` and `--without` argu To view the docs that were originally generated by this repository and hosted by Salt Project, the following should generate a local copy of the documentation. + # Clear any locally generated documentation + rm -rf html/ + # Generate HTML documentation of kitchen-salt + bundle install + bundle exec yard doc + firefox html/index.html + + # OPTIONAL + # Start a local http server to view the rendered docs + # Accessible via http://localhost:8808/ bundle exec yard server docroot=html/ ## Setup ## From 1074939dc4f62bc89c53d772b729e282bf1bf9af Mon Sep 17 00:00:00 2001 From: ScriptAutomate Date: Fri, 9 Apr 2021 15:23:44 -0500 Subject: [PATCH 3/6] One more note on where to autogen local html docs --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 9cfbe7c..80c458b 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,9 @@ This provisioner is tested with kitchen-docker against CentOS, Ubuntu, and Debia You'll need the test-kitchen and kitchen-salt gem's installed in your system, along with kitchen-vagrant or some other suitable driver for test-kitchen. Please see the [gettingstarted documentation](docs/gettingstarted.md). +To generate more detailed documentation of ruby classes, in an HTML rendered local website for viewing, +please the documentation on how to [Generate and locally view docs](docs/gettingstarted.md#generate-and-locally-view-docs). + ## Provisioner Options ## More details on all the configuration options are in the [provisioner_options documentation](docs/provisioner_options.md). From 7fa2d2bc4752a202006d5c056e8a140959eee65f Mon Sep 17 00:00:00 2001 From: ScriptAutomate Date: Fri, 9 Apr 2021 15:34:43 -0500 Subject: [PATCH 4/6] Remain with 2.6.3 for target ruby version --- docs/gettingstarted.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md index 5715429..d4660df 100644 --- a/docs/gettingstarted.md +++ b/docs/gettingstarted.md @@ -33,10 +33,10 @@ The following instructions will allow for a global install of rbenv. 1. Install ruby and set it as the version to use by default - rbenv install 2.6.7 - rbenv local 2.6.7 + rbenv install 2.6.3 + rbenv local 2.6.3 # OPTIONAL: Set global default version - # rbenv global 2.6.7 + # rbenv global 2.6.3 If gemsets are needed, the [rbenv-gemset](https://github.com/jf/rbenv-gemset) plugin can be added to the gemsets repository. From fc600d49c18ad3afa9bbb526c837c04113b1f566 Mon Sep 17 00:00:00 2001 From: ScriptAutomate Date: Fri, 9 Apr 2021 15:40:16 -0500 Subject: [PATCH 5/6] Add note about target ruby version in rbenv guide --- docs/gettingstarted.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md index d4660df..24a4944 100644 --- a/docs/gettingstarted.md +++ b/docs/gettingstarted.md @@ -31,7 +31,7 @@ The following instructions will allow for a global install of rbenv. - [Basic GitHub Checkout/setup of rbenv](https://github.com/rbenv/rbenv#basic-github-checkout) - [Installation of `ruby-build`](https://github.com/rbenv/ruby-build#installation) -1. Install ruby and set it as the version to use by default +1. Install ruby and set `2.6.3` as the version to use by default. Salt uses this version of Ruby in CI pipelines, which is why it is preferred here, but newer version of ruby may work without issue. rbenv install 2.6.3 rbenv local 2.6.3 From 61bcf94ccb33c8bb72e3fa20bf2535a9b41ada12 Mon Sep 17 00:00:00 2001 From: ScriptAutomate Date: Fri, 9 Apr 2021 15:42:03 -0500 Subject: [PATCH 6/6] Typo fix --- docs/gettingstarted.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md index 24a4944..1c00cad 100644 --- a/docs/gettingstarted.md +++ b/docs/gettingstarted.md @@ -31,7 +31,7 @@ The following instructions will allow for a global install of rbenv. - [Basic GitHub Checkout/setup of rbenv](https://github.com/rbenv/rbenv#basic-github-checkout) - [Installation of `ruby-build`](https://github.com/rbenv/ruby-build#installation) -1. Install ruby and set `2.6.3` as the version to use by default. Salt uses this version of Ruby in CI pipelines, which is why it is preferred here, but newer version of ruby may work without issue. +1. Install ruby and set `2.6.3` as the version to use by default. Salt uses this version of Ruby in CI pipelines, which is why it is preferred here, but newer versions of ruby may work without issue. rbenv install 2.6.3 rbenv local 2.6.3