Skip to content

Commit 117eeac

Browse files
gjtorikiangreptile-apps[bot]claude
authored
feat(docs): publish YARD API docs + llms.txt to GitHub Pages (#480)
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 5f970be commit 117eeac

8 files changed

Lines changed: 156 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Publish API Docs
2+
on:
3+
push:
4+
tags: ['v*']
5+
workflow_dispatch:
6+
permissions:
7+
contents: read
8+
concurrency:
9+
group: pages
10+
cancel-in-progress: false
11+
jobs:
12+
build:
13+
runs-on: ubuntu-latest
14+
permissions:
15+
contents: read
16+
steps:
17+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
18+
- uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
19+
with:
20+
bundler-cache: true
21+
- run: ./script/docs
22+
- uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
23+
- name: Archive site
24+
run: |
25+
tar \
26+
--dereference --hard-dereference \
27+
--directory docs/_site \
28+
-cvf "$RUNNER_TEMP/artifact.tar" \
29+
--exclude=.git \
30+
--exclude=.github \
31+
.
32+
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
33+
with:
34+
name: github-pages
35+
path: ${{ runner.temp }}/artifact.tar
36+
retention-days: 1
37+
if-no-files-found: error
38+
deploy:
39+
needs: build
40+
environment:
41+
name: github-pages
42+
url: ${{ steps.deployment.outputs.page_url }}
43+
runs-on: ubuntu-latest
44+
steps:
45+
- uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
46+
id: deployment

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,5 @@
5050

5151
.vscode
5252
.idea/
53+
docs/_site/
54+
.yardoc/

‎.yardopts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
--output-dir docs/_site
2+
--markup markdown
3+
lib/**/*.rb
4+
-
5+
README.md
6+
CHANGELOG.md

‎Gemfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,9 @@
33
source "https://rubygems.org"
44

55
gemspec
6+
7+
group :docs do
8+
gem "yard"
9+
gem "yard-markdown"
10+
gem "webrick"
11+
end

‎Gemfile.lock‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,10 @@ GEM
1717
crack (1.0.1)
1818
bigdecimal
1919
rexml
20+
csv (3.3.5)
21+
date (3.5.1)
2022
drb (2.2.3)
23+
erb (6.0.4)
2124
hashdiff (1.2.1)
2225
json (2.19.4)
2326
jwt (3.1.2)
@@ -33,10 +36,17 @@ GEM
3336
ast (~> 2.4.1)
3437
racc
3538
prism (1.9.0)
39+
psych (5.3.1)
40+
date
41+
stringio
3642
public_suffix (7.0.5)
3743
racc (1.8.1)
3844
rainbow (3.1.1)
3945
rake (13.4.2)
46+
rdoc (7.2.0)
47+
erb
48+
psych (>= 4.0.0)
49+
tsort
4050
regexp_parser (2.12.0)
4151
rexml (3.4.4)
4252
rubocop (1.84.2)
@@ -70,13 +80,21 @@ GEM
7080
standard-performance (1.9.0)
7181
lint_roller (~> 1.1)
7282
rubocop-performance (~> 1.26.0)
83+
stringio (3.2.0)
84+
tsort (0.2.0)
7385
unicode-display_width (3.2.0)
7486
unicode-emoji (~> 4.1)
7587
unicode-emoji (4.2.0)
7688
webmock (3.26.2)
7789
addressable (>= 2.8.0)
7890
crack (>= 0.3.2)
7991
hashdiff (>= 0.4.0, < 2.0.0)
92+
webrick (1.9.2)
93+
yard (0.9.43)
94+
yard-markdown (0.7.1)
95+
csv
96+
rdoc
97+
yard
8098
zeitwerk (2.7.5)
8199

82100
PLATFORMS
@@ -89,15 +107,21 @@ DEPENDENCIES
89107
rake
90108
standard (~> 1.49)
91109
webmock (~> 3.26)
110+
webrick
92111
workos!
112+
yard
113+
yard-markdown
93114

94115
CHECKSUMS
95116
addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
96117
ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
97118
base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
98119
bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
99120
crack (1.0.1) sha256=ff4a10390cd31d66440b7524eb1841874db86201d5b70032028553130b6d4c7e
121+
csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
122+
date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
100123
drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
124+
erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
101125
hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
102126
json (2.19.4) sha256=670a7d333fb3b18ca5b29cb255eb7bef099e40d88c02c80bd42a3f30fe5239ac
103127
jwt (3.1.2) sha256=af6991f19a6bb4060d618d9add7a66f0eeb005ac0bc017cd01f63b42e122d535
@@ -108,10 +132,12 @@ CHECKSUMS
108132
parallel (1.28.0) sha256=33e6de1484baf2524792d178b0913fc8eb94c628d6cfe45599ad4458c638c970
109133
parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
110134
prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
135+
psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
111136
public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
112137
racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
113138
rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
114139
rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
140+
rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
115141
regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
116142
rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
117143
rubocop (1.84.2) sha256=5692cea54168f3dc8cb79a6fe95c5424b7ea893c707ad7a4307b0585e88dbf5f
@@ -121,10 +147,15 @@ CHECKSUMS
121147
standard (1.54.0) sha256=7a4b08f83d9893083c8f03bc486f0feeb6a84d48233b40829c03ef4767ea0100
122148
standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
123149
standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
150+
stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
151+
tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
124152
unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
125153
unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
126154
webmock (3.26.2) sha256=774556f2ea6371846cca68c01769b2eac0d134492d21f6d0ab5dd643965a4c90
155+
webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
127156
workos (7.1.2)
157+
yard (0.9.43) sha256=cf8733a8f0485df2a162927e9b5f182215a61f6d22de096b8f402c726a1c5821
158+
yard-markdown (0.7.1) sha256=06c378632dfe7ba053be9ba469eb4701aa0470e36bcf7e5546f353eb90c1bfd1
128159
zeitwerk (2.7.5) sha256=d8da92128c09ea6ec62c949011b00ed4a20242b255293dd66bf41545398f73dd
129160

130161
BUNDLED WITH

‎script/docs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/bin/sh
2+
set -eu
3+
cd "$(dirname "$0")/.."
4+
bundle config set --local with 'docs'
5+
bundle install
6+
rm -rf docs/_site
7+
# 1. Generate HTML docs (default YARD format).
8+
bundle exec yard doc
9+
# 2. Generate Markdown docs alongside the HTML, using the yard-markdown plugin.
10+
# We point output at the same docs/_site directory so .md files land next to .html.
11+
# --no-cache forces a re-parse so the markdown formatter sees fresh registry data.
12+
# --plugin yard-markdown ensures the plugin is loaded without relying on ~/.yard/config.
13+
bundle exec yard doc --plugin yard-markdown --format markdown --no-cache --output-dir docs/_site
14+
# 3. Generate llms.txt (index) from the markdown output, so the published site
15+
# is consumable by LLM tooling.
16+
bundle exec ./script/llms-txt

‎script/docs-serve‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/bin/sh
2+
set -eu
3+
cd "$(dirname "$0")/.."
4+
bundle config set --local with 'docs'
5+
bundle install --quiet
6+
if [ "${1:-}" = "--static" ]; then
7+
if [ ! -d docs/_site ]; then
8+
./script/docs
9+
fi
10+
exec bundle exec ruby -run -e httpd -- docs/_site -p 4000
11+
fi
12+
exec bundle exec yard server --reload --port 4000

‎script/llms-txt‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#!/usr/bin/env ruby
2+
# frozen_string_literal: true
3+
4+
# Generates llms.txt (curated index) from the Markdown docs produced by
5+
# `yard --format markdown` in docs/_site. See https://llmstxt.org for the format.
6+
7+
require "pathname"
8+
9+
ROOT = Pathname.new(__dir__).join("..").expand_path
10+
SITE = ROOT.join("docs/_site")
11+
require ROOT.join("lib/workos/version").to_s
12+
13+
abort "docs/_site is missing — run script/docs first" unless SITE.directory?
14+
15+
md_files = Pathname.glob(SITE.join("**/*.md")).sort_by { |p| p.relative_path_from(SITE).to_s }
16+
17+
title_for = lambda do |path|
18+
first_heading = path.each_line.lazy.map(&:strip).find { |l| l.start_with?("# ") }
19+
first_heading ? first_heading.sub(/^#\s+/, "").sub(/\s*<a id=.*?<\/a>\s*$/, "").strip : path.basename(".md").to_s
20+
end
21+
22+
index_lines = []
23+
index_lines << "# WorkOS Ruby SDK v#{WorkOS::VERSION}"
24+
index_lines << ""
25+
index_lines << "> API client for WorkOS. This file indexes the auto-generated YARD documentation for the `workos` gem so language models can locate per-class references."
26+
index_lines << ""
27+
index_lines << "## API Reference"
28+
index_lines << ""
29+
md_files.each do |path|
30+
rel = path.relative_path_from(SITE).to_s
31+
index_lines << "- [#{title_for.call(path)}](#{rel})"
32+
end
33+
index_lines << ""
34+
35+
SITE.join("llms.txt").write(index_lines.join("\n"))
36+
37+
puts "Wrote #{SITE.join("llms.txt")} (#{md_files.size} entries)"

0 commit comments

Comments
 (0)