Skip to content

Commit 579c6bb

Browse files
david-waltermiredavid-waltermire
authored
docs: expand website documentation with guides and architecture (#633)
* docs: expand website with installation, building, and guide pages - Add installation.md.vm with Maven/Gradle dependencies and snapshots - Add building.md.vm with JDK 17 requirement and CI profile instructions - Add claude-integration.md.vm documenting Claude Code plugin skills - Add 7 guide pages covering module loading, code generation, data binding, Metapath queries, constraint validation, schema generation, and architecture - Update site.xml with Documentation and Guides navigation menus - Enhance index.md.vm with quick start and feature overview * docs: left-justify prerequisite tables * fix: address PR review feedback - Use canonical URL framework.metaschema.dev instead of pages.nist.gov - Fix @nonnull placement claim (on getter/setter, not field) - Remove non-existent builder pattern example - Fix Severity enum to IConstraint.Level in CustomHandler example - Fix shell-completion to generate-completion in README * fix: add missing imports to code examples in documentation - validating-with-constraints.md.vm: Fixed incorrect API examples - Replaced non-existent setConstraintValidationEnabled with correct API - Updated to use IBoundLoader.enableFeature() and validateWithConstraints() - Replaced custom handler example with FindingCollectingConstraintValidationHandler - generating-schemas.md.vm: Already fixed (previous session) - Added Writer, Files, Path imports to XSD generation - Added imports to JSON Schema generation - Added XMLConstants, StreamSource, File, SAXException to XML validation - Added complete imports to JSON validation - loading-metaschema-modules.md.vm: Added missing imports - Added IOException and Path imports to error handling example - Added INamedModelDefinition, IAssemblyDefinition, IFieldDefinition imports - reading-writing-data.md.vm: Added missing imports - Added Stream, Files, Path imports to batch processing example - Fixed DefaultBindingContext() to IBindingContext.newInstance() - executing-metapath.md.vm: Added missing imports - Added Map, ConcurrentHashMap imports to MetapathCache example
1 parent de8725e commit 579c6bb

14 files changed

+2841
-13
lines changed

‎README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,37 @@ To disable colored output, use the `--no-color` flag:
117117
metaschema-cli --no-color <command>
118118
```
119119

120+
#### Shell Completion
121+
122+
The CLI supports tab completion for Bash and Zsh shells, providing intelligent suggestions for commands, subcommands, and options.
123+
124+
**Bash:**
125+
126+
```bash
127+
# Generate and source completion (temporary, current session only)
128+
source <(metaschema-cli shell-completion bash)
129+
130+
# Or save to a file and source it in your ~/.bashrc for persistence
131+
metaschema-cli shell-completion bash > ~/.metaschema-completion.bash
132+
echo 'source ~/.metaschema-completion.bash' >> ~/.bashrc
133+
```
134+
135+
**Zsh:**
136+
137+
```zsh
138+
# Ensure your completions directory exists
139+
mkdir -p ~/.zsh/completions
140+
141+
# Generate completion script
142+
metaschema-cli shell-completion zsh > ~/.zsh/completions/_metaschema-cli
143+
144+
# Add to your ~/.zshrc if not already configured
145+
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
146+
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
147+
```
148+
149+
After setting up completion, restart your shell or source the configuration file.
150+
120151
## Relationship to prior work
121152

122153
The contents of this repository is based on work from the [Metaschema Java repository](https://github.com/usnistgov/metaschema-java/) maintained by the National Institute of Standards and Technology (NIST), the [contents of which have been dedicated in the worldwide public domain](https://github.com/usnistgov/metaschema-java/blob/1a496e4bcf905add6b00a77a762ed3cc31bf77e6/LICENSE.md) using the [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) public domain dedication. This repository builds on this prior work, maintaining the [CCO license](https://github.com/metaschema-framework/metaschema-java/blob/main/LICENSE.md) on any new works in this repository.

‎src/site/markdown/building.md.vm‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Building from Source
2+
3+
This guide explains how to build the Metaschema Java project from source code.
4+
5+
## Prerequisites
6+
7+
| Requirement | Minimum Version | Notes |
8+
|:------------|:----------------|:------|
9+
| Java JDK | 17 | Required for building (output JARs are JDK 11 compatible) |
10+
| Maven | 3.9.0 | Required for building |
11+
| Git | 2.0 | Required for cloning |
12+
13+
Ensure `JAVA_HOME` is set correctly:
14+
15+
```bash
16+
# Linux/macOS
17+
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
18+
19+
# Windows
20+
set JAVA_HOME=C:\Program Files\Java\jdk-17
21+
```
22+
23+
## Clone the Repository
24+
25+
Clone the repository with submodules:
26+
27+
```bash
28+
git clone --recurse-submodules https://github.com/metaschema-framework/metaschema-java.git
29+
cd metaschema-java
30+
```
31+
32+
If you already cloned without submodules, initialize them:
33+
34+
```bash
35+
git submodule update --init --recursive
36+
```
37+
38+
## Build Commands
39+
40+
### Basic Build
41+
42+
Build and install to your local Maven repository:
43+
44+
```bash
45+
mvn install
46+
```
47+
48+
### Run Tests Only
49+
50+
```bash
51+
mvn test
52+
```
53+
54+
### Run a Single Test
55+
56+
```bash
57+
# Run a single test class
58+
mvn test -Dtest=MetaschemaModuleTest
59+
60+
# Run a single test method
61+
mvn test -Dtest=MetaschemaModuleTest#testLoadModule
62+
```
63+
64+
### Skip Tests
65+
66+
```bash
67+
mvn install -DskipTests
68+
```
69+
70+
### CI/CD Build
71+
72+
Replicate the full CI/CD build (recommended before pushing):
73+
74+
```bash
75+
mvn install -PCI -Prelease
76+
```
77+
78+
This enables additional checks including:
79+
80+
- License header verification
81+
- Checkstyle code style checks
82+
- SpotBugs static analysis
83+
- Full test suite
84+
85+
## Code Quality Commands
86+
87+
### Check License Headers
88+
89+
```bash
90+
mvn license:check
91+
```
92+
93+
### Auto-format Source Code
94+
95+
```bash
96+
mvn formatter:format
97+
```
98+
99+
### Check for Checkstyle Issues
100+
101+
```bash
102+
mvn checkstyle:check
103+
```
104+
105+
## Common Build Issues
106+
107+
### Submodule Not Initialized
108+
109+
**Symptom:** Build fails with missing Metaschema schema files.
110+
111+
**Solution:** Initialize submodules:
112+
113+
```bash
114+
git submodule update --init --recursive
115+
```
116+
117+
### Java Version Mismatch
118+
119+
**Symptom:** Compilation errors or "unsupported class file version" errors.
120+
121+
**Solution:** Ensure you're using Java 17 or later for building:
122+
123+
```bash
124+
java -version
125+
mvn -version
126+
```
127+
128+
### Maven Version Too Old
129+
130+
**Symptom:** Build fails with plugin compatibility errors or enforcer rule failures.
131+
132+
**Solution:** Upgrade Maven to 3.9.0 or later:
133+
134+
```bash
135+
mvn -version
136+
```
137+
138+
### Out of Memory
139+
140+
**Symptom:** Build fails with `OutOfMemoryError`.
141+
142+
**Solution:** Increase Maven's heap size:
143+
144+
```bash
145+
export MAVEN_OPTS="-Xmx2g"
146+
mvn install
147+
```
148+
149+
## Building the Site
150+
151+
To build the project documentation site:
152+
153+
```bash
154+
mvn site
155+
```
156+
157+
The generated site appears in `target/site/`. For multi-module builds, each module's site is in its respective `target/site/` directory.
158+
159+
## Contributing
160+
161+
For contribution guidelines, including code style requirements and the pull request process, see [CONTRIBUTING.md](${project.scm.url}/blob/develop/CONTRIBUTING.md).
162+
163+
## Next Steps
164+
165+
- [Installation](installation.html) - Add the library to your project
166+
- [Architecture](guides/architecture.html) - Understand the module structure

‎src/site/markdown/claude-integration.md.vm‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Using with Claude Code
2+
3+
[Claude Code](https://claude.ai/code) is an AI-powered coding assistant that can help you work with Metaschema and OSCAL tools more effectively.
4+
5+
## Overview
6+
7+
Claude Code plugins provide specialized skills for:
8+
9+
- **Metaschema authoring** - Creating and validating Metaschema modules
10+
- **OSCAL document creation** - Building catalogs, profiles, SSPs
11+
- **CLI assistance** - Running commands and interpreting output
12+
- **Metapath expressions** - Writing and debugging queries
13+
14+
## Prerequisites
15+
16+
1. [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code)
17+
2. Install the [Metaschema plugins](https://github.com/metaschema-framework/claude-plugins/tree/main)
18+
19+
## Available Plugins
20+
21+
### Metaschema Plugin
22+
23+
Skills for working with Metaschema definitions:
24+
25+
| Skill | Description |
26+
|:------|:------------|
27+
| `metaschema:metaschema-basics` | Introduction to Metaschema concepts |
28+
| `metaschema:metaschema-module-authoring` | Creating and modifying modules |
29+
| `metaschema:metaschema-constraints-authoring` | Defining validation constraints |
30+
| `metaschema:metapath-expressions` | Writing Metapath queries |
31+
32+
### OSCAL Plugin
33+
34+
Skills for working with OSCAL documents:
35+
36+
| Skill | Description |
37+
|:------|:------------|
38+
| `oscal:oscal-basics` | OSCAL document types and structure |
39+
40+
### Tool Plugins
41+
42+
Skills for using CLI and library tools:
43+
44+
| Skill | Description |
45+
|:------|:------------|
46+
| `oscal-tools:using-oscal-cli` | Running oscal-cli commands |
47+
| `metaschema-tools:using-metaschema-java` | Using the Metaschema Java library |
48+
49+
### Development Plugin
50+
51+
For contributors to the Metaschema framework:
52+
53+
| Skill | Description |
54+
|:------|:------------|
55+
| `dev-metaschema:development-workflow` | TDD, debugging, testing patterns |
56+
| `dev-metaschema:repo-organization` | Project structure and relationships |
57+
| `dev-metaschema:unit-test-writing` | Writing comprehensive tests |
58+
59+
## Example Workflows
60+
61+
### Generate Java Classes from Metaschema
62+
63+
Ask Claude:
64+
> "Help me set up the Maven plugin to generate Java classes from my Metaschema module"
65+
66+
Claude will guide you through the plugin configuration and code generation process.
67+
68+
### Write a Metapath Expression
69+
70+
Ask Claude:
71+
> "Help me write a Metapath expression that finds all controls with a specific property"
72+
73+
Claude will use the Metapath skill to construct and explain the expression.
74+
75+
### Validate a Metaschema Module
76+
77+
Ask Claude:
78+
> "Validate my Metaschema module at `src/main/metaschema/my-model.xml`"
79+
80+
Claude will run validation and explain any errors.
81+
82+
### Debug Constraint Errors
83+
84+
Ask Claude:
85+
> "I'm getting constraint validation errors. Can you help me understand what's wrong?"
86+
87+
Claude will analyze the errors, explain the constraint requirements, and suggest fixes.
88+
89+
## Tips for Effective Use
90+
91+
1. **Be specific** - Mention file paths and exact error messages
92+
2. **Provide context** - Share relevant portions of your Metaschema definitions
93+
3. **Ask for explanations** - Claude can explain why something is required by the specification
94+
4. **Request examples** - Ask for sample code or Metaschema snippets
95+
96+
## Integration with This Library
97+
98+
When working with the Metaschema Java library, Claude can help you:
99+
100+
- Configure the Maven plugin for code generation
101+
- Write code using generated binding classes
102+
- Execute Metapath queries programmatically
103+
- Implement custom constraint validators
104+
- Troubleshoot serialization and deserialization issues
105+
106+
## Learn More
107+
108+
For more information about Claude Code and the technologies used in this project:
109+
110+
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
111+
- [Metaschema Specification](https://framework.metaschema.dev/specification/)
112+
- [Metapath Reference](https://framework.metaschema.dev/specification/metapath/)

0 commit comments

Comments
 (0)