actiondoc 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93d5b5065266ea804bd9ec0900e26f7d5adcff589e2ed8420a8a82db27c73645
-  data.tar.gz: 4d7b319c346f3cf5dc5249403075561428a164e17af2351a392310c9b45bbd0f
+  metadata.gz: e3c58562841476b25f7b28ff0773199fbfceff01c050793e0b4f8b37ae0b9fad
+  data.tar.gz: 9e73c913a023a357e09ed9cae8f4af10c89ee32c68e9c779194bd5d30a7ac78c
 SHA512:
-  metadata.gz: 87e10ec6a11240a4a1bfd0794b972f8c3a0e0a0366f948a7670b18b0c675672ac7541b3d4446912278d0be15884a3fec5c62e736d0ec9c6abf0aadcb71eb9cab
-  data.tar.gz: fa61a6c0cb713c0b98c7e53177cac5f4c2997c5299ffc97a647b0534f9177da52e707425353d223a02ba9b847cf6d550be9a1266a5ef84163a24440214399a7b
+  metadata.gz: cdee99862d92e906e4d1f90d848374948edb0da86efc21be6adc5a7203ab253d496af9889b38af41a189e6ac044e0e2d9d37dfd97afb25b1c853f5c0da6320ba
+  data.tar.gz: 2224a87cac9fc2c8332adcc4e37bf22bf574702b3f3e5f66362a7ed85fdff5af40fe09fd68ac4a42bbc0252d4b912a1786c2600f24bc8c0f587fd0085da47836

data/.dockerignore

@@ -1,3 +1,4 @@
+.github/
 bin/
 features/
 test/

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at aisrael@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/actiondoc.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'Ruby Gem to generate documentation for GitHub Actions'
   spec.homepage      = 'https://github.com/aisrael/actiondoc'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('~> 2.7.1')
+  spec.required_ruby_version = Gem::Requirement.new('~> 3.2.2')
 
   # spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
 

data/lib/actiondoc/generator.rb

@@ -6,7 +6,25 @@ require 'ostruct'
 require 'table_layouts'
 require 'yaml'
 
-TEMPLATES_DIR = File.expand_path('templates', __dir__)
+DEFAULT_TEMPLATE = <<~ERB
+  <%= action.name %>
+  ====
+
+  <%= action.description %>
+
+  <%= inputs_section -%>
+ERB
+
+TEMPLATE_WITHOUT_INPUTS = <<~ERB
+  <%= action.name %>
+  ====
+
+  <%= action.description %>
+
+  ## Inputs
+
+  This action has no inputs.
+ERB
 
 module ActionDoc
   # The documentation generator class
@@ -21,33 +39,58 @@ module ActionDoc
     end
 
     def run
+      check_action_yml
       action = read_action_yml
-      template_filename = options[:template] || File.join(TEMPLATES_DIR, 'default.erb')
-      render_template(template_filename, action)
+      template = read_template(action)
+      render_template(template, action)
+    end
+
+    def read_template(action)
+      options_template = options[:template]
+      if options_template
+        unless File.readable?(options_template)
+          warn "Template file #{options_template} not found! Aborting..."
+          exit 1
+        end
+        ERB.new(File.read(options_template), trim_mode: '-')
+      elsif action.inputs && !action.inputs.empty?
+        ERB.new(DEFAULT_TEMPLATE, trim_mode: '-')
+      else
+        ERB.new(TEMPLATE_WITHOUT_INPUTS, trim_mode: '-')
+      end
+    end
+
+    def check_action_yml
+      @path_to_action_yml = @args.first || 'action.yml'
+      return if File.readable?(@path_to_action_yml)
+
+      warn "#{@path_to_action_yml} not found! Aborting..."
+      exit 1
     end
 
     def read_action_yml
-      yaml = YAML.safe_load(File.read('action.yml')).deep_symbolize_keys
+      yaml = YAML.safe_load(File.read(@path_to_action_yml)).deep_symbolize_keys
       inputs = yaml.fetch(:inputs, {}).map do |k, v|
-        Input.new(k, v[:description], v[:required] ? 'Required' : 'No', v[:default])
+        Input.new(k, v[:description].chomp, v[:required] ? 'Required' : 'No', v[:default])
       end
-      Action.new(*(yaml.values_at(:name, :description) + [inputs]))
+      Action.new(yaml[:name], yaml[:description].chomp, inputs)
     end
 
-    def render_template(template_filename, action)
+    def render_template(template, action)
       inputs_table = construct_inputs_table(action)
-      template = ERB.new(File.read(template_filename), trim_mode: '-')
       model = TemplateModel.new(action, inputs_table)
       puts template.result(model.instance_eval { binding })
     end
 
     def construct_inputs_table(action)
+      return unless action.inputs && !action.inputs.empty?
+
       TableLayouts::Nice.new(Input.members_as_headers, action.inputs).layout
     end
   end
 
+  # For ERB binding
   INPUTS_SECTION_ERB = <<~ERB
-
     ## Inputs
 
     <% inputs_table.each do |row| -%>
@@ -55,10 +98,17 @@ module ActionDoc
     <% end -%>
   ERB
 
+  NO_INPUTS = <<~NO_INPUTS
+
+    ## Inputs
+
+    This action has no inputs.
+  NO_INPUTS
+
   # For ERB binding
   TemplateModel = Struct.new(:action, :inputs_table) do
     def inputs_section
-      return if inputs_table.nil? || inputs_table.empty?
+      return NO_INPUTS if inputs_table.nil? || inputs_table.empty?
 
       ERB.new(INPUTS_SECTION_ERB, trim_mode: '-').result(binding)
     end

data/lib/actiondoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionDoc
-  VERSION = '0.1.0'
+  VERSION = '0.4.0'
 end

data/lib/actiondoc.rb

@@ -13,11 +13,7 @@ module ActionDoc
     def run
       options = parse_options
 
-      if options[:version]
-        display_version
-      else
-        ActionDoc::Generator.new(ARGV, options).run
-      end
+      ActionDoc::Generator.new(ARGV, options).run
     end
 
     # Builds the OptionParser and parses the options
@@ -39,23 +35,30 @@ module ActionDoc
     # Builds and returns the OptionParser
     def build_optparser(options)
       OptionParser.new do |opts|
-        opts.banner = 'Usage: actiondoc [options]'
+        opts.banner = <<~BANNER
+          Usage:
+
+              actiondoc [options] [ACTION_YAML_FILE]
+
+          Where:
+              [ACTION_YAML_FILE]               is the path to the action.yaml file. Defaults to "action.yaml"
+                                               in the current directory.
+
+          Options:
+        BANNER
 
         opts.on('--template=TEMPLATE_FILENAME', '-t=TEMPLATE_FILENAME', 'The template to use') do |template_filename|
           options[:template] = template_filename
         end
         opts.on('--version', 'Show the version') do
-          options[:version] = true
+          puts "actiondoc v#{ActionDoc::VERSION}"
+          exit
         end
         opts.on('--help', 'Display this help text') do
           puts opts
+          exit
         end
       end
     end
-
-    # Print out the version (in the VERSION file)
-    def display_version
-      puts "actiondoc v#{ActionDoc::VERSION}"
-    end
   end
 end

data/templates/README.md.erb

@@ -4,9 +4,13 @@
 [![Tests](https://github.com/aisrael/actiondoc/actions/workflows/tests.yml/badge.svg)](https://github.com/aisrael/actiondoc/actions/workflows/tests.yml)
 
 <%= action.description %>
+
 <%= inputs_section -%>
 
-See [Basic Usage](features/basic_usage.feature) for some basic usage.
+actiondoc is both a Ruby Gem _and_ a GitHub Action that uses that gem to generate a suitable `README.md` from
+an optional ERB template, intended to help keep your own action's documentation up-to-date with the actual inputs.
+
+See [Basic Usage](features/basic_usage.feature) for some basic usage of the gem.
 
 ### Example
 
@@ -20,7 +24,7 @@ name: actiondoc
   inputs:
     path-to-action-yml:
       description: >-
-        The path to the `action.yml` file to generate documentation for.
+        The path to the `action.yml` file
         required: false
 ```
 
@@ -34,7 +38,81 @@ Generates documentation from your GitHub Action's `action.yml`
 
 ## Inputs
 
-| Name               | Description                                                      | Required | Default |
-|--------------------|------------------------------------------------------------------|----------|---------|
-| path-to-action-yml | The path to the `action.yml` file to generate documentation for. | No       |         |
+| Name               | Description                       | Required | Default |
+|--------------------|-----------------------------------|----------|---------|
+| path-to-action-yml | The path to the `action.yml` file | No       |         |
+```
+
+## Use it in a workflow to update your action's README
+
+### Commit & push directly to update the README.md
+
+The following sample workflow uses this repository as a GitHub Action directly, and commits the updated
+README.md directly.
+
+
+```yaml
+name: Generate README
+on:
+  push:
+    paths:
+      - action.yml
+      - README.md.erb
+
+jobs:
+  generate-readme:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: if [ -f README.md ]; then rm README.md; fi
+      - name: Generate README
+        uses: aisrael/actiondoc@v1
+        with:
+          template-filename: README.md.erb
+          output-filename: README.md
+      - run: |
+          cat README.md
+      - name: Commit & Push changes
+        uses: actions-js/push@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+
+### Create a PR to update the README.md
+
+The following sample workflow uses this repository as a GitHub Action directly, and creates a PR (using
+[peter-evans/create-pull-request](https://github.com/peter-evans/create-pull-request)) to
+update `README.md` on any changes to either `action.yml` or `README.md.erb`.
+
+
+```yaml
+name: Generate README
+on:
+  push:
+    paths:
+      - action.yml
+      - README.md.erb
+
+jobs:
+  generate-readme:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: if [ -f README.md ]; then rm README.md; fi
+      - name: Generate README
+        uses: aisrael/actiondoc@v1
+        with:
+          template-filename: README.md.erb
+          output-filename: README.md
+      - run: |
+          cat README.md
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v4
+        with:
+          add-paths: README.md
+          base: main
+          branch: update-readme
+          delete-branch: true
+          title: Update README.md
 ```

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actiondoc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alistair Israel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-11-29 00:00:00.000000000 Z
+date: 2023-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aruba
@@ -131,12 +131,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".dockerignore"
-- ".github/workflows/README.md.no-template"
-- ".github/workflows/README.md.with-template"
-- ".github/workflows/action-tests.yml"
-- ".github/workflows/docker-build.yml"
-- ".github/workflows/generate-readme.yml"
-- ".github/workflows/tests.yml"
+- CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE
 - actiondoc.gemspec
@@ -144,7 +139,6 @@ files:
 - lib/action.rb
 - lib/actiondoc.rb
 - lib/actiondoc/generator.rb
-- lib/actiondoc/templates/default.erb
 - lib/actiondoc/version.rb
 - lib/table_layouts.rb
 - templates/README.md.erb
@@ -164,14 +158,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: 2.7.1
+      version: 3.2.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Generate documentation for GitHub Actions

data/.github/workflows/README.md.no-template

@@ -1,13 +0,0 @@
-actiondoc
-====
-
-Generates documentation from your GitHub Action's `action.yml`
-
-## Inputs
-
-| Name               | Description                                                                             | Required | Default |
-|--------------------|-----------------------------------------------------------------------------------------|----------|---------|
-| template-filename  | The path to the ERB template to use to generate the documentation.                      | No       |         |
-| output-filename    | The filename to save the output to. If not specified, simply prints to standard output. | No       |         |
-| path-to-action-yml | The path to the `action.yml` file to generate documentation for.                        | No       |         |
-| working-directory  | The directory to perform the action in, if not $GITHUB_WORKSPACE                        | No       |         |

data/.github/workflows/README.md.with-template

@@ -1,48 +0,0 @@
-actiondoc
-====
-
-[![Tests](https://github.com/aisrael/actiondoc/actions/workflows/tests.yml/badge.svg)](https://github.com/aisrael/actiondoc/actions/workflows/tests.yml)
-
-Generates documentation from your GitHub Action's `action.yml`
-
-## Inputs
-
-| Name               | Description                                                                             | Required | Default |
-|--------------------|-----------------------------------------------------------------------------------------|----------|---------|
-| template-filename  | The path to the ERB template to use to generate the documentation.                      | No       |         |
-| output-filename    | The filename to save the output to. If not specified, simply prints to standard output. | No       |         |
-| path-to-action-yml | The path to the `action.yml` file to generate documentation for.                        | No       |         |
-| working-directory  | The directory to perform the action in, if not $GITHUB_WORKSPACE                        | No       |         |
-
-See [Basic Usage](features/basic_usage.feature) for some basic usage.
-
-### Example
-
-Given an `action.yml` that contains:
-
-```yaml
-name: actiondoc
-  description: >-
-    Generates documentation from your GitHub Action's `action.yml`
-
-  inputs:
-    path-to-action-yml:
-      description: >-
-        The path to the `action.yml` file to generate documentation for.
-        required: false
-```
-
-Then when running `actiondoc` it should output
-
-```markdown
-actiondoc
-====
-
-Generates documentation from your GitHub Action's `action.yml`
-
-## Inputs
-
-| Name               | Description                                                      | Required | Default |
-|--------------------|------------------------------------------------------------------|----------|---------|
-| path-to-action-yml | The path to the `action.yml` file to generate documentation for. | No       |         |
-```

data/.github/workflows/action-tests.yml

@@ -1,42 +0,0 @@
-name: Action Tests
-on: push
-
-jobs:
-  test-with-defaults:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - run: |
-          ls -l .
-      - name: Given
-        run: if [ -f README.md ]; then rm README.md; fi
-      - name: Test with defaults
-        uses: ./.
-        with:
-          output-filename: README.md
-      - run: |
-          ls -l .
-      - name: Assertions
-        run: |
-          cat README.md
-          [ -f README.md ] && diff README.md .github/workflows/README.md.no-template
-
-  test-with-template:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - run: |
-          ls -l .
-      - name: Given
-        run: if [ -f README.md ]; then rm README.md; fi
-      - name: Test with defaults
-        uses: ./.
-        with:
-          template-filename: templates/README.md.erb
-          output-filename: README.md
-      - run: |
-          ls -l .
-      - name: Assertions
-        run: |
-          cat README.md
-          [ -f README.md ] && diff README.md .github/workflows/README.md.with-template

data/.github/workflows/docker-build.yml

@@ -1,46 +0,0 @@
-name: Build Docker Image
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - "!.github/workflows/**"
-      - .github/workflows/docker-build.yml
-      - "lib/**"
-      - "exe/**"
-      - actiondoc.gemspec
-      - Dockerfile
-      - Gemfile
-      - Rakefile
-
-jobs:
-  docker-build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
-      # So now you can use Actions' own caching!
-      - name: Cache Docker layers
-        uses: actions/cache@v3
-        with:
-          path: /tmp/.buildx-cache
-          key: ${{ runner.os }}-buildx-${{ inputs.git-hash || github.sha }}
-          restore-keys: |
-            ${{ runner.os }}-buildx-
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v2
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - run: |
-          rake build
-      - name: Build and push
-        uses: docker/build-push-action@v3
-        with:
-          context: .
-          push: true
-          tags: |
-            ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}:latest
-            ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}:0.1.0

data/.github/workflows/generate-readme.yml

@@ -1,27 +0,0 @@
-name: Generate README
-on:
-  push:
-    paths:
-      - action.yml
-      - templates/**
-
-jobs:
-  generate-readme:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - run: if [ -f README.md ]; then rm README.md; fi
-      - name: Test with defaults
-        uses: ./.
-        with:
-          template-filename: templates/README.md.erb
-          output-filename: README.md
-      - run: |
-          cat README.md
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v4
-        with:
-          add-paths: README.md
-          branch: update-readme
-          delete-branch: true
-          title: Update README.md

data/.github/workflows/tests.yml

@@ -1,49 +0,0 @@
-name: Rubocop and Tests
-on:
-  push:
-    paths-ignore:
-      - README.md
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  rubocop:
-    name: Rubocop
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          # runs 'bundle install' and caches installed gems automatically
-          bundler-cache: true
-      - name: Run RuboCop
-        run: bundle exec rubocop --parallel
-
-  unit-tests:
-    name: Unit tests
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          bundler-cache: true
-      - name: Run the tests
-        run: bundle exec rake test
-
-  cucumber-tests:
-    name: Cucumber tests
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          bundler-cache: true
-      - name: Run the tests
-        run: bundle exec cucumber

data/lib/actiondoc/templates/default.erb

@@ -1,5 +0,0 @@
-<%= action.name %>
-====
-
-<%= action.description %>
-<%= inputs_section -%>