diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml new file mode 100644 index 0000000..bfe74ae --- /dev/null +++ b/.github/workflows/publish-docs.yaml @@ -0,0 +1,30 @@ +name: Huxley TechDocs + +on: + workflow_dispatch: + push: + branches: master + paths: + - "docs/**" + - "mkdocs.yml" + - ".github/workflows/publish-docs.yaml" + pull_request: + branches: master + paths: + - "docs/**" + - "mkdocs.yaml" + - ".github/workflows/publish-docs.yaml" + schedule: + - cron: "15 3 1 * *" + +concurrency: huxley-techdocs-${{ github.ref }} + +jobs: + publish-techdocs: + uses: simplybusiness/github-action-reusable-workflows/.github/workflows/techdocs.yaml@v1 + with: + repo: "github-action-reusable-workflows" + secrets: + region: ${{ secrets.AWS_LIVE_CICD_REGION }} + aws-access-key-id: ${{ secrets.AWS_LIVE_CICD_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_LIVE_CICD_SECRET_ACCESS_KEY }} diff --git a/README.md b/README.md index cd1319a..6092975 100644 --- a/README.md +++ b/README.md @@ -1,115 +1 @@ -[![Build Status](https://semaphoreci.com/api/v1/projects/e488365d-9c57-4431-916a-72aea091d1b5/229083/shields_badge.svg)](https://semaphoreci.com/simplybusiness/rulezilla) -[![Code Climate](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/badges/76b47eaeffc33e312508/gpa.svg)](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/feed) -[![Gem Version](https://badge.fury.io/rb/rulezilla.svg)](http://badge.fury.io/rb/rulezilla) - -rulezilla -========= - -This provides a DSL to implement rules for various tasks. In the current version we are still relying on user to have a certain level of Ruby knowledge -in order to be able to use this DSL. The ultimate goal is for people without prior Ruby knowledge to be able to change and even write the Rule. - - -# Installation - -## Using `Gemfile` - -Add the following line to your `Gemfile`: - - gem 'rulezilla' - -Then run: - - bundle install - -## Without `Gemfile` - -On your command line run the following: - - gem install 'rulezilla' - -## Usage - -### Rules - -Rules are defined in Ruby. Rules are classes that include the `Rulezilla::DSL`. - -#### Ruby - -You can use plain Ruby to define the rule classes. But you will need to include the `Rulezilla::DSL` module. That will give you access to the DSL used to define rules. - -Here is an example: - - class RoboticsRule - include Rulezilla::DSL - - group :may_not_injure_human do - condition { not_injure_human? } - - group :obey_human do - condition { do_as_human_told? } - - define :protect_its_own_existence do - condition { protect_itself? } - result(true) - end - end - end - - default(false) - - end - -Please refer to the [feature](spec/features/rulezilla_dsl_framework.feature) for further details of the DSL. - -### Support Module - -The support module will be automatically included if its name is `"#{rule_class_name}Support"` - -e.g. if the rule class name is `RoboticsRule`, then the support would be `RoboticsRuleSupport` - - module RoboticsRuleSupport - def protect_itself? - in_danger? && not_letting_itself_be_detroyed? - end - end - -### How to execute the rule - -If the entity is: - - entity = { - not_injure_human?: true, - do_as_human_told?: true, - in_danger?: true, - not_letting_itself_be_detroyed?: true - } - -#### To get the first matching result output - - RoboticsRule.apply(entity) #=> true - -#### To get all matching result outputs - - RoboticsRule.all(entity) #=> [true, false] - -Note that `false` is the result outcome coming out from `default(false)` on top level, which is also called `root node`. The `root` node does not have any condition and hence -it is considered to be matching. This means, by consequence, that its result (`default(false)`) is included in the list of matching result outputs which `#all(entity)` above -returns. - -#### To get the trace of all nodes - - RoboticsRule.trace(entity) - #=> all the nodes instance: [root, may_not_injure_human, obey_human, protect_its_own_existence] in sequence order. - -#### To get all results from the Rule - - RoboticsRule.results #=> [true, false] - - -### Syntax - -Please refer to the features for DSL syntax: - -[DSL Feature](spec/features/rulezilla_dsl_framework.feature), - -[Default Support Methods Feature](spec/features/default_support_methods.feature) +All documentation is now in the `docs/` subdirectory, or can be viewed in rendered form on Backstage. Start with the [index](docs/index.md) \ No newline at end of file diff --git a/_pipeline/stage_publishdocs.yml b/_pipeline/stage_publishdocs.yml new file mode 100644 index 0000000..0c9b57f --- /dev/null +++ b/_pipeline/stage_publishdocs.yml @@ -0,0 +1,9 @@ +version: 0.2 + +phases: + install: + commands: + - docker_setup + build: + commands: + - run_huxley publish_backstage_docs diff --git a/catalog-info.yaml b/catalog-info.yaml index 0854d75..cfa9b41 100644 --- a/catalog-info.yaml +++ b/catalog-info.yaml @@ -2,7 +2,9 @@ apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: rulezilla - description: Rule DSL + description: Rule DSL + annotations: + backstage.io/techdocs-ref: dir:. spec: type: library lifecycle: production diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..cd1319a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,115 @@ +[![Build Status](https://semaphoreci.com/api/v1/projects/e488365d-9c57-4431-916a-72aea091d1b5/229083/shields_badge.svg)](https://semaphoreci.com/simplybusiness/rulezilla) +[![Code Climate](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/badges/76b47eaeffc33e312508/gpa.svg)](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/feed) +[![Gem Version](https://badge.fury.io/rb/rulezilla.svg)](http://badge.fury.io/rb/rulezilla) + +rulezilla +========= + +This provides a DSL to implement rules for various tasks. In the current version we are still relying on user to have a certain level of Ruby knowledge +in order to be able to use this DSL. The ultimate goal is for people without prior Ruby knowledge to be able to change and even write the Rule. + + +# Installation + +## Using `Gemfile` + +Add the following line to your `Gemfile`: + + gem 'rulezilla' + +Then run: + + bundle install + +## Without `Gemfile` + +On your command line run the following: + + gem install 'rulezilla' + +## Usage + +### Rules + +Rules are defined in Ruby. Rules are classes that include the `Rulezilla::DSL`. + +#### Ruby + +You can use plain Ruby to define the rule classes. But you will need to include the `Rulezilla::DSL` module. That will give you access to the DSL used to define rules. + +Here is an example: + + class RoboticsRule + include Rulezilla::DSL + + group :may_not_injure_human do + condition { not_injure_human? } + + group :obey_human do + condition { do_as_human_told? } + + define :protect_its_own_existence do + condition { protect_itself? } + result(true) + end + end + end + + default(false) + + end + +Please refer to the [feature](spec/features/rulezilla_dsl_framework.feature) for further details of the DSL. + +### Support Module + +The support module will be automatically included if its name is `"#{rule_class_name}Support"` + +e.g. if the rule class name is `RoboticsRule`, then the support would be `RoboticsRuleSupport` + + module RoboticsRuleSupport + def protect_itself? + in_danger? && not_letting_itself_be_detroyed? + end + end + +### How to execute the rule + +If the entity is: + + entity = { + not_injure_human?: true, + do_as_human_told?: true, + in_danger?: true, + not_letting_itself_be_detroyed?: true + } + +#### To get the first matching result output + + RoboticsRule.apply(entity) #=> true + +#### To get all matching result outputs + + RoboticsRule.all(entity) #=> [true, false] + +Note that `false` is the result outcome coming out from `default(false)` on top level, which is also called `root node`. The `root` node does not have any condition and hence +it is considered to be matching. This means, by consequence, that its result (`default(false)`) is included in the list of matching result outputs which `#all(entity)` above +returns. + +#### To get the trace of all nodes + + RoboticsRule.trace(entity) + #=> all the nodes instance: [root, may_not_injure_human, obey_human, protect_its_own_existence] in sequence order. + +#### To get all results from the Rule + + RoboticsRule.results #=> [true, false] + + +### Syntax + +Please refer to the features for DSL syntax: + +[DSL Feature](spec/features/rulezilla_dsl_framework.feature), + +[Default Support Methods Feature](spec/features/default_support_methods.feature) diff --git a/lib/rulezilla/version.rb b/lib/rulezilla/version.rb index 6a602c9..234644d 100644 --- a/lib/rulezilla/version.rb +++ b/lib/rulezilla/version.rb @@ -1,5 +1,5 @@ # frozen_string_literal: true module Rulezilla - VERSION = '0.4.5' + VERSION = '0.4.6' end diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 0000000..66de144 --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,8 @@ +site_name: Rulezilla Docs +repo_url: https://github.com/simplybusiness/rulezilla +edit_uri: blob/master/docs/ +docs_dir: "docs" +nav: + - Home: index.md +plugins: + - techdocs-core