Skip to content

Commit 6da4e3c

Browse files
ejbleysejbleys
committed
2 parents 2fd4634 + f0a3e97 commit 6da4e3c

28 files changed

+1867
-25
lines changed

‎.github/workflows/build.yml‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,26 @@ on:
77

88
jobs:
99
build:
10-
name: Generate XSD documentation
10+
name: Generate documentation
1111
runs-on: ubuntu-latest
1212
steps:
13-
- uses: actions/checkout@v3
13+
- uses: actions/checkout@v4
1414
- name: Setup prerequisites
1515
run: |
1616
sudo apt-get update
17-
sudo apt-get install -y curl make libxml2-dev libxslt-dev libnode-dev node-gyp libssl-dev npm openssl xsltproc
18-
- name: Setup snaps
19-
run: |
20-
sudo snap install yq
21-
- name: Use Ruby
22-
uses: actions/setup-ruby@v1
17+
sudo apt-get install -y xsltproc
18+
- uses: ruby/setup-ruby@v1
2319
with:
24-
ruby-version: '3.1'
25-
- name: Build XSD documentation
20+
ruby-version: '3.3'
21+
bundler-cache: true
22+
- name: Update schemas.yml and build documentation
2623
run: |
27-
make _xsddoc
24+
# Set cache directory to a location in the runner's workspace
25+
export HRMA_CACHE_DIR=$GITHUB_WORKSPACE/.hrma-cache
26+
27+
# Update schemas manifest
28+
bundle exec hrma schemas manifest update
29+
30+
# Build documentation with parallel processing
31+
echo "Building documentation with parallel processing using Fractor..."
32+
bundle exec hrma build documentation --workers=2

‎.github/workflows/deploy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414
run: |
1515
echo "##[set-output name=value;]deploy_${GITHUB_REF##*/}"
1616
- name: Trigger dependent repositories
17-
uses: peter-evans/repository-dispatch@v1
17+
uses: peter-evans/repository-dispatch@v3
1818
with:
1919
token: ${{ secrets.PAT_TOKEN }}
2020
repository: ISO-TC211/schemas.isotc211.org

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@ xsl/
55
.archive/
66
.vscode/
77
19115/newProject.xpr
8+
_site/

‎Gemfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
source 'https://rubygems.org'
2+
3+
gem 'rake', '~> 13.0'
4+
gem "rspec"
5+
6+
gemspec

‎README.adoc‎

Lines changed: 207 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,230 @@
1-
= ISO/TC 211 XML Schemas
1+
= ISO/TC 211 Schemas
22

3-
image:https://github.com/ISO-TC211/schemas/workflows/build/badge.svg["XSD documentation build status", link="https://github.com/ISO-TC211/schemas/actions?workflow=build"]
3+
image:https://github.com/ISO-TC211/schemas/workflows/build/badge.svg["Documentation build status", link="https://github.com/ISO-TC211/schemas/actions?workflow=build"]
44

55
image:https://github.com/ISO-TC211/schemas/workflows/deploy/badge.svg["Deploy status", link="https://github.com/ISO-TC211/schemas/actions?workflow=deploy"]
66

7+
78
== Introduction
89

9-
This is the official repository of ISO/TC 211 XML Schemas.
10+
This is the official repository of ISO/TC 211 Schemas, jointly managed by
11+
ISO/TC 211/XMG and Ribose.
12+
13+
== Requirements
14+
15+
* Dependencies installation (choose one):
16+
- Individual: `gem install thor rake`
17+
- Using Bundler: `bundle install`
18+
- Build and install gem: `gem build hrma.gemspec && gem install hrma-*.gem`
19+
* External dependencies:
20+
- Java (for generating diagrams)
21+
- xsltproc (for generating documentation)
22+
23+
24+
== Command-line reference
25+
26+
=== General
27+
28+
The repository includes a command-line tool called `hrma` (Harmonized Resources
29+
Maintenance Agency) to manage schemas and generate documentation.
30+
31+
32+
=== Schema management
33+
34+
The `schemas` command manages the schema manifest file (`schemas.yml`), which
35+
controls which schemas should generate documentation.
36+
37+
[source,sh]
38+
----
39+
bundle exec hrma schemas manifest SUBCOMMAND
40+
----
41+
42+
Available subcommands:
43+
44+
* `update` - Update schemas.yml with all 3-character XSD and JSON files
45+
* `list` - List all schemas in the manifest file
46+
** `--type TYPE` - Filter by schema type (xsd or json)
47+
** `--doc DOC` - Filter by document number
48+
* `validate` - Verify all schemas in the manifest exist
49+
50+
[example]
51+
====
52+
[source,sh]
53+
----
54+
# Update schemas.yml with all 3-character XSD and JSON files
55+
bundle exec hrma schemas manifest update
56+
57+
# List all schemas in the manifest file
58+
bundle exec hrma schemas manifest list
1059
11-
Jointly managed by ISO/TC 211/XMG and Ribose.
60+
# List only XSD schemas
61+
bundle exec hrma schemas manifest list --type xsd
1262
63+
# List schemas for document 19115
64+
bundle exec hrma schemas manifest list --doc 19115
1365
14-
== XSD documentation pages
66+
# Verify all schemas in the manifest exist
67+
bundle exec hrma schemas manifest validate
68+
----
69+
====
70+
71+
=== Documentation generation
72+
73+
The `build` command generates documentation for schemas defined in the manifest file.
74+
75+
[source,sh]
76+
----
77+
bundle exec hrma build SUBCOMMAND [OPTIONS]
78+
----
79+
80+
Available subcommands:
81+
82+
* `documentation` - Generate documentation for schemas
83+
** `--manifest-path PATH` - Path to schemas.yml manifest file
84+
** `--cache-dir DIR` - Directory for caching downloaded tools
85+
** `--log-dir DIR` - Directory for storing log files
86+
** `--parallel` / `--no-parallel` - Enable/disable parallel processing with Fractors (default: enabled)
87+
** `--workers NUM` - Number of parallel workers to use (default: auto-configured)
88+
* `clean` - Remove generated documentation
89+
* `distclean` - Remove generated documentation and downloaded tools
90+
** `--global-cache` - Also clean the global cache directory
91+
92+
Examples:
1593

16-
XSD documentation pages are generated using the `build` workflow.
94+
[source,sh]
95+
----
96+
# Generate documentation for schemas
97+
bundle exec hrma build documentation
98+
99+
# Generate documentation with custom manifest file
100+
bundle exec hrma build documentation --manifest-path=custom-schemas.yml
101+
102+
# Generate documentation with 4 workers
103+
bundle exec hrma build documentation --workers=4
104+
105+
# Generate documentation without parallel processing
106+
bundle exec hrma build documentation --no-parallel
17107
18-
The `schemas.yml` file controls which schemas (identified by path)
19-
should generate XSD documentation.
108+
# Remove generated documentation
109+
bundle exec hrma build clean
110+
111+
# Remove generated documentation and downloaded tools
112+
bundle exec hrma build distclean
113+
----
20114

21115
The resulting documentation per schema will be generated in the path:
22116

23117
* HTML page: `_site/{schema-path}/{xsd-name}/index.html`
24118
* Diagrams: `_site/{schema-path}/{xsd-name}/diagrams/*.svg`
25119

120+
=== Configuration management
26121

27-
== Building documentation
122+
The `config` command manages configuration settings.
28123

29124
[source,sh]
30125
----
31-
# removes generated artifacts
32-
make clean
126+
bundle exec hrma config SUBCOMMAND
127+
----
128+
129+
Available subcommands:
130+
131+
* `get KEY` - Get a configuration value
132+
* `set KEY VALUE` - Set a configuration value
33133

34-
# makes _site
35-
make all
134+
Supported configuration keys:
135+
136+
* `cache_dir` - Directory for caching downloaded tools (default: `~/.hrma/cache`)
137+
* `log_dir` - Directory for storing log files (default: `~/.hrma/logs`)
138+
139+
You can set configuration in three ways (in order of precedence):
140+
141+
. Command-line option: `--cache-dir=/path/to/cache`
142+
. Environment variable: `HRMA_CACHE_DIR=/path/to/cache bundle exec hrma ...`
143+
. Configuration file: `~/.hrma/config.yml`
144+
145+
Examples:
146+
147+
[source,sh]
148+
----
149+
# Get current cache directory
150+
bundle exec hrma config get cache_dir
151+
152+
# Set cache directory
153+
bundle exec hrma config set cache_dir /path/to/cache
154+
----
155+
156+
157+
== Advanced features
158+
159+
=== Parallel processing
160+
161+
The tool supports parallel processing using Ruby's Ractor feature through the Fractor framework. This
162+
significantly speeds up documentation generation for large numbers of schema files.
163+
164+
By default, the tool automatically determines the optimal number of workers to
165+
use based on your system resources:
166+
167+
* In "auto" mode (default), the number of workers is determined by:
168+
** Using half of your CPU cores (rounded down)
169+
** Ensuring at least 2 cores are left free for system processes
170+
** Using at least 1 worker
171+
** Using one worker per file when possible (up to the calculated maximum)
172+
173+
This auto-configuration provides a good balance between performance and system
174+
responsiveness.
175+
176+
[example]
177+
====
178+
* With 4 files on a 4-core system: 1 worker would be used (half cores = 2, but ensuring 2 cores are free = 1)
179+
* With 4 files on an 8-core system: 4 workers would be used (half cores = 4, which leaves enough free cores)
180+
* With 4 files on a 16-core system: 4 workers would be used (one per file, even though 8 workers would be available)
181+
* With 10 files on a 16-core system: 8 workers would be used (half cores = 8, which is less than file count)
182+
====
183+
184+
You can manually specify the number of workers:
185+
186+
[source,sh]
36187
----
188+
# Use 4 workers for parallel processing
189+
bundle exec hrma build documentation --workers=4
190+
----
191+
192+
To disable parallel processing entirely:
193+
194+
[source,sh]
195+
----
196+
# Disable parallel processing
197+
bundle exec hrma build documentation --no-parallel
198+
----
199+
200+
201+
== Code organization
202+
203+
The `hrma` tool is organized into several components:
204+
205+
=== Command-line interface
206+
207+
* `bin/hrma` - Main executable script
208+
* `lib/hrma/cli.rb` - Thor-based CLI implementation
209+
* `lib/hrma/commands/*.rb` - Individual command implementations
210+
211+
=== Build system
212+
213+
* `lib/hrma/build/document_generator.rb` - Main class for generating documentation
214+
* `lib/hrma/build/schema_processor.rb` - Processes individual schema files
215+
* `lib/hrma/build/schema_work.rb` - Work item representation for parallel processing
216+
* `lib/hrma/build/schema_worker.rb` - Worker implementation for parallel processing
217+
* `lib/hrma/build/tools.rb` - Handles downloading and setting up external tools
218+
* `lib/hrma/build/cleaner.rb` - Handles cleaning generated files
219+
220+
=== Configuration
221+
222+
* `lib/hrma/config.rb` - Configuration management
223+
* `lib/hrma/version.rb` - Version information
224+
225+
226+
== Copyright and license
227+
228+
Schemas copyright ISO/TC 211.
229+
230+
Other files copyright Ribose Inc.

‎bin/hrma‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/usr/bin/env ruby
2+
# frozen_string_literal: true
3+
4+
# Main executable for the hrma tool
5+
# This script is the entry point for the command-line interface
6+
7+
require "thor"
8+
require_relative "../lib/hrma/cli"
9+
10+
# Start the CLI with command-line arguments
11+
Hrma::Cli.start(ARGV)

‎hrma.gemspec‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
require_relative 'lib/hrma/version'
2+
3+
Gem::Specification.new do |spec|
4+
spec.name = "hrma"
5+
spec.version = Hrma::VERSION
6+
spec.authors = ["Ribose Inc."]
7+
spec.email = ["[email protected]"]
8+
spec.summary = %q{Management utility for the ISO/TC 211 Harmonized Resources Maintenance Agency}
9+
spec.description = %q{Command-line tool for managing ISO/TC 211 Harmonized Resources Maintenance Agency repositories.}
10+
spec.homepage = "https://www.ribose.com/"
11+
spec.license = "MIT"
12+
13+
spec.files = Dir.glob("{bin,lib}/**/*") + %w(Gemfile README.adoc)
14+
spec.executables = ["hrma"]
15+
spec.require_paths = ["lib"]
16+
17+
spec.required_ruby_version = '>= 3.0.0'
18+
19+
spec.add_dependency "thor", "~> 1.2"
20+
spec.add_dependency "rake", "~> 13.0"
21+
spec.add_dependency "ruby-progressbar", "~> 1.13"
22+
spec.add_dependency "fractor", "~> 0.1"
23+
end

0 commit comments

Comments
 (0)