Skip to content

Commit d305aa8

Browse files
LightningStairsLightningStairs
authored
Merge pull request #40 from simplybusiness/add-techdocs-config-files
Add techdocs
2 parents ea53576 + acdae76 commit d305aa8

File tree

7 files changed

+167
-117
lines changed

7 files changed

+167
-117
lines changed

‎.github/workflows/publish-docs.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Huxley TechDocs
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches: master
7+
paths:
8+
- "docs/**"
9+
- "mkdocs.yml"
10+
- ".github/workflows/publish-docs.yaml"
11+
pull_request:
12+
branches: master
13+
paths:
14+
- "docs/**"
15+
- "mkdocs.yaml"
16+
- ".github/workflows/publish-docs.yaml"
17+
schedule:
18+
- cron: "15 3 1 * *"
19+
20+
concurrency: huxley-techdocs-${{ github.ref }}
21+
22+
jobs:
23+
publish-techdocs:
24+
uses: simplybusiness/github-action-reusable-workflows/.github/workflows/techdocs.yaml@v1
25+
with:
26+
repo: "github-action-reusable-workflows"
27+
secrets:
28+
region: ${{ secrets.AWS_LIVE_CICD_REGION }}
29+
aws-access-key-id: ${{ secrets.AWS_LIVE_CICD_ACCESS_KEY_ID }}
30+
aws-secret-access-key: ${{ secrets.AWS_LIVE_CICD_SECRET_ACCESS_KEY }}

‎README.md‎

Lines changed: 1 addition & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -1,115 +1 @@
1-
[![Build Status](https://semaphoreci.com/api/v1/projects/e488365d-9c57-4431-916a-72aea091d1b5/229083/shields_badge.svg)](https://semaphoreci.com/simplybusiness/rulezilla)
2-
[![Code Climate](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/badges/76b47eaeffc33e312508/gpa.svg)](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/feed)
3-
[![Gem Version](https://badge.fury.io/rb/rulezilla.svg)](http://badge.fury.io/rb/rulezilla)
4-
5-
rulezilla
6-
=========
7-
8-
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
9-
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.
10-
11-
12-
# Installation
13-
14-
## Using `Gemfile`
15-
16-
Add the following line to your `Gemfile`:
17-
18-
gem 'rulezilla'
19-
20-
Then run:
21-
22-
bundle install
23-
24-
## Without `Gemfile`
25-
26-
On your command line run the following:
27-
28-
gem install 'rulezilla'
29-
30-
## Usage
31-
32-
### Rules
33-
34-
Rules are defined in Ruby. Rules are classes that include the `Rulezilla::DSL`.
35-
36-
#### Ruby
37-
38-
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.
39-
40-
Here is an example:
41-
42-
class RoboticsRule
43-
include Rulezilla::DSL
44-
45-
group :may_not_injure_human do
46-
condition { not_injure_human? }
47-
48-
group :obey_human do
49-
condition { do_as_human_told? }
50-
51-
define :protect_its_own_existence do
52-
condition { protect_itself? }
53-
result(true)
54-
end
55-
end
56-
end
57-
58-
default(false)
59-
60-
end
61-
62-
Please refer to the [feature](spec/features/rulezilla_dsl_framework.feature) for further details of the DSL.
63-
64-
### Support Module
65-
66-
The support module will be automatically included if its name is `"#{rule_class_name}Support"`
67-
68-
e.g. if the rule class name is `RoboticsRule`, then the support would be `RoboticsRuleSupport`
69-
70-
module RoboticsRuleSupport
71-
def protect_itself?
72-
in_danger? && not_letting_itself_be_detroyed?
73-
end
74-
end
75-
76-
### How to execute the rule
77-
78-
If the entity is:
79-
80-
entity = {
81-
not_injure_human?: true,
82-
do_as_human_told?: true,
83-
in_danger?: true,
84-
not_letting_itself_be_detroyed?: true
85-
}
86-
87-
#### To get the first matching result output
88-
89-
RoboticsRule.apply(entity) #=> true
90-
91-
#### To get all matching result outputs
92-
93-
RoboticsRule.all(entity) #=> [true, false]
94-
95-
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
96-
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
97-
returns.
98-
99-
#### To get the trace of all nodes
100-
101-
RoboticsRule.trace(entity)
102-
#=> all the nodes instance: [root, may_not_injure_human, obey_human, protect_its_own_existence] in sequence order.
103-
104-
#### To get all results from the Rule
105-
106-
RoboticsRule.results #=> [true, false]
107-
108-
109-
### Syntax
110-
111-
Please refer to the features for DSL syntax:
112-
113-
[DSL Feature](spec/features/rulezilla_dsl_framework.feature),
114-
115-
[Default Support Methods Feature](spec/features/default_support_methods.feature)
1+
All documentation is now in the `docs/` subdirectory, or can be viewed in rendered form on Backstage. Start with the [index](docs/index.md)

‎_pipeline/stage_publishdocs.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
version: 0.2
2+
3+
phases:
4+
install:
5+
commands:
6+
- docker_setup
7+
build:
8+
commands:
9+
- run_huxley publish_backstage_docs

‎catalog-info.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@ apiVersion: backstage.io/v1alpha1
22
kind: Component
33
metadata:
44
name: rulezilla
5-
description: Rule DSL
5+
description: Rule DSL
6+
annotations:
7+
backstage.io/techdocs-ref: dir:.
68
spec:
79
type: library
810
lifecycle: production

‎docs/index.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +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)
2+
[![Code Climate](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/badges/76b47eaeffc33e312508/gpa.svg)](https://codeclimate.com/repos/53ecc0416956800c1d01f6bf/feed)
3+
[![Gem Version](https://badge.fury.io/rb/rulezilla.svg)](http://badge.fury.io/rb/rulezilla)
4+
5+
rulezilla
6+
=========
7+
8+
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
9+
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.
10+
11+
12+
# Installation
13+
14+
## Using `Gemfile`
15+
16+
Add the following line to your `Gemfile`:
17+
18+
gem 'rulezilla'
19+
20+
Then run:
21+
22+
bundle install
23+
24+
## Without `Gemfile`
25+
26+
On your command line run the following:
27+
28+
gem install 'rulezilla'
29+
30+
## Usage
31+
32+
### Rules
33+
34+
Rules are defined in Ruby. Rules are classes that include the `Rulezilla::DSL`.
35+
36+
#### Ruby
37+
38+
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.
39+
40+
Here is an example:
41+
42+
class RoboticsRule
43+
include Rulezilla::DSL
44+
45+
group :may_not_injure_human do
46+
condition { not_injure_human? }
47+
48+
group :obey_human do
49+
condition { do_as_human_told? }
50+
51+
define :protect_its_own_existence do
52+
condition { protect_itself? }
53+
result(true)
54+
end
55+
end
56+
end
57+
58+
default(false)
59+
60+
end
61+
62+
Please refer to the [feature](spec/features/rulezilla_dsl_framework.feature) for further details of the DSL.
63+
64+
### Support Module
65+
66+
The support module will be automatically included if its name is `"#{rule_class_name}Support"`
67+
68+
e.g. if the rule class name is `RoboticsRule`, then the support would be `RoboticsRuleSupport`
69+
70+
module RoboticsRuleSupport
71+
def protect_itself?
72+
in_danger? && not_letting_itself_be_detroyed?
73+
end
74+
end
75+
76+
### How to execute the rule
77+
78+
If the entity is:
79+
80+
entity = {
81+
not_injure_human?: true,
82+
do_as_human_told?: true,
83+
in_danger?: true,
84+
not_letting_itself_be_detroyed?: true
85+
}
86+
87+
#### To get the first matching result output
88+
89+
RoboticsRule.apply(entity) #=> true
90+
91+
#### To get all matching result outputs
92+
93+
RoboticsRule.all(entity) #=> [true, false]
94+
95+
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
96+
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
97+
returns.
98+
99+
#### To get the trace of all nodes
100+
101+
RoboticsRule.trace(entity)
102+
#=> all the nodes instance: [root, may_not_injure_human, obey_human, protect_its_own_existence] in sequence order.
103+
104+
#### To get all results from the Rule
105+
106+
RoboticsRule.results #=> [true, false]
107+
108+
109+
### Syntax
110+
111+
Please refer to the features for DSL syntax:
112+
113+
[DSL Feature](spec/features/rulezilla_dsl_framework.feature),
114+
115+
[Default Support Methods Feature](spec/features/default_support_methods.feature)

‎lib/rulezilla/version.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# frozen_string_literal: true
22

33
module Rulezilla
4-
VERSION = '0.4.5'
4+
VERSION = '0.4.6'
55
end

‎mkdocs.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
site_name: Rulezilla Docs
2+
repo_url: https://github.com/simplybusiness/rulezilla
3+
edit_uri: blob/master/docs/
4+
docs_dir: "docs"
5+
nav:
6+
- Home: index.md
7+
plugins:
8+
- techdocs-core

0 commit comments

Comments
 (0)