Add GitHub Actions workflow for deploying Lrama documentation to GitHub Pages

.github/workflows/gh-pages.yml

@@ -0,0 +1,46 @@
+name: Deploy Lrama documentation to GitHub Pages
+
+on:
+  push:
+    branches: ["master"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: ${{ github.repository == 'ruby/lrama' && !startsWith(github.event_name, 'pull') }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@f26937343756480a8cb3ae1f623b9c8d89ed6984 # v1.196.0
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with Lrama
+        run: bundle exec rake rdoc
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -10,3 +10,4 @@
 /tmp/
 /vendor/bundle
 /.idea/
+_site/

.rdoc_options

@@ -0,0 +1,2 @@
+page_dir: doc
+warn_missing_rdoc_ref: true

Gemfile

@@ -7,6 +7,7 @@ gemspec
 gem "pry"
 gem "racc", "1.8.1"
 gem "rake"
+gem "rdoc"
 gem "rspec"
 gem "simplecov", require: false
 gem "stackprof", platforms: [:ruby] # stackprof doesn't support Windows

Rakefile

@@ -15,6 +15,13 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
 end
 task :spec => "build:parser"
 
+require "rdoc/task"
+RDoc::Task.new do |rdoc|
+  rdoc.title = "Lrama Documentation"
+  rdoc.main = "Index.md"
+  rdoc.rdoc_dir = "_site"
+end
+
 desc "steep check"
 task :steep do
   sh "bundle exec steep check"

doc/Index.md

@@ -0,0 +1,58 @@
+# Lrama
+
+[![Gem Version](https://badge.fury.io/rb/lrama.svg)](https://badge.fury.io/rb/lrama)
+[![build](https://github.com/ruby/lrama/actions/workflows/test.yaml/badge.svg)](https://github.com/ruby/lrama/actions/workflows/test.yaml)
+
+
+## Overview
+
+Lrama is LALR (1) parser generator written by Ruby. The first goal of this project is providing error tolerant parser for CRuby with minimal changes on CRuby parse.y file.
+
+## Installation
+
+Lrama's installation is simple. You can install it via RubyGems.
+
+```shell
+$ gem install lrama
+```
+
+From source codes, you can install it as follows:
+
+```shell
+$ cd "$(lrama root)"
+$ bundle install
+$ bundle exec rake install
+$ bundle exec lrama --version
+lrama 0.6.11
+```
+## Usage
+
+Lrama is a command line tool. You can generate a parser from a grammar file by running `lrama` command.
+
+```shell
+# "y.tab.c" and "y.tab.h" are generated
+$ lrama -d sample/parse.y
+```
+Specify the output file with `-o` option. The following example generates "calc.c" and "calc.h".
+
+```shell
+# "calc", "calc.c", and "calc.h" are generated
+$ lrama -d sample/calc.y -o calc.c && gcc -Wall calc.c -o calc && ./calc
+Enter the formula:
+1
+=> 1
+1+2*3
+=> 7
+(1+2)*3
+=> 9
+```
+
+## Supported Ruby version
+
+Lrama is executed with BASERUBY when building ruby from source code. Therefore Lrama needs to support BASERUBY, currently 2.5, or later version.
+
+This also requires Lrama to be able to run with only default gems because BASERUBY runs with `--disable=gems` option.
+
+## License
+
+See [LEGAL.md](https://github.com/ruby/lrama/blob/master/LEGAL.md) file.