Skip to content

Commit

Permalink
Autogenerate docs based on json schema
Browse files Browse the repository at this point in the history
  • Loading branch information
@quincylvania
quincylvania committed Apr 22, 2024
1 parent bc41ebf commit e4afb03
Show file tree
Hide file tree
Showing 8 changed files with 107 additions and 134 deletions.
4 changes: 3 additions & 1 deletion .github/workflows/deploy-production.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@ jobs:
run: npm install
- name: Validate the source files 🔬
run: npm run validate
- name: Generate thumbnail images 🖨️
- name: Generate docs 🖨️
run: npm run docs
- name: Generate thumbnail images 🗜️
run: npm run thumbnails

- name: Install and Build 🔧
Expand Down
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@
_site
Gemfile.lock
img-thumbnails
docs
10 changes: 5 additions & 5 deletions _tools/frontmatter-validator/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ if (isStrict) {
forceProperties: true,
noEmptyArrays: true,
noEmptyStrings: true,
noExtraKeywords: true,
//noExtraKeywords: true,
noTypeless: true,
};
Object.assign(zSchemaOptions, strictOptions);
Expand Down Expand Up @@ -86,10 +86,10 @@ function validateFrontmatter(path, schemaPath) {
const directory = path.dirname(fileURLToPath(import.meta.url));
var schemasDir = path.join(directory, '/schemas');

validateFrontmatter(sourcePath + '/_posts', schemasDir + '/post.json');
validateFrontmatter(sourcePath + '/_people', schemasDir + '/person.json');
validateFrontmatter(sourcePath + '/_pages', schemasDir + '/page.json');
validateFrontmatter(sourcePath + '/_redirects', schemasDir + '/redirect.json');
validateFrontmatter(sourcePath + '/_posts', schemasDir + '/post.schema.json');
validateFrontmatter(sourcePath + '/_people', schemasDir + '/person.schema.json');
validateFrontmatter(sourcePath + '/_pages', schemasDir + '/page.schema.json');
validateFrontmatter(sourcePath + '/_redirects', schemasDir + '/redirect.schema.json');

if (hasInvalid) {
// nonzero exit for GitHub Actions
Expand Down
165 changes: 63 additions & 102 deletions ...s/frontmatter-validator/schemas/page.json → ...matter-validator/schemas/page.schema.json
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,56 @@
{
"title": "Page",
"title": "page",
"$id": "dogwood/page.schema.json",
"description": "A generic information page not tied to a datetime.",
"type": "object",
"$defs": {
"labeledLink": {
"title": "labeled link",
"type": "object",
"properties": {
"label": {
"type": "string"
},
"link": {
"type": "string"
}
}
},
"labeledLinks": {
"title": "labeled links",
"type": "array",
"items": {
"$ref": "#/$defs/labeledLink"
}
},
"swagItem": {
"type": "object",
"title": "swag item",
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
},
"image": {
"type": "string"
}
}
},
"swagItems": {
"title": "swag items",
"type": "array",
"items": {
"$ref": "#/$defs/swagItem"
}
}
},
"properties": {
"title": {
"type": "string"
"type": "string",
"title": "title",
"examples": ["My Great Page"]
},
"temp_title": {
"type": "string"
Expand Down Expand Up @@ -99,124 +146,36 @@
"donate": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"link": {
"type": "string"
}
}
}
},
"swag_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
},
"image": {
"type": "string"
}
}
}
"$ref": "#/$defs/swagItems"
},
"swag_sections": {
"title": "swag sections",
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
},
"image": {
"type": "string"
}
}
}
}
}
"$ref": "#/$defs/swagItems"
}
},
"links": {
"$ref": "#/$defs/labeledLinks"
},
"dropdown_links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"link": {
"type": "string"
}
}
}
"$ref": "#/$defs/labeledLinks"
},
"app_links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"link": {
"type": "string"
}
}
}
"$ref": "#/$defs/labeledLinks"
},
"footer_links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"link": {
"type": "string"
}
}
}
"$ref": "#/$defs/labeledLinks"
},
"buttons": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"link": {
"type": "string"
}
}
}
"$ref": "#/$defs/labeledLinks"
},
"sessions": {
"type": "array",
"title": "sessions",
"items": {
"title": "session",
"type": "object",
"properties": {
"title": {
Expand All @@ -242,6 +201,7 @@
},
"section_tags": {
"type": "array",
"title": "section tags",
"items": {
"type": "string"
}
Expand Down Expand Up @@ -276,6 +236,7 @@
"format": "date-time"
},
"map": {
"title": "map",
"type": "object",
"properties": {
"points": {
Expand Down
6 changes: 5 additions & 1 deletion ...frontmatter-validator/schemas/person.json → ...tter-validator/schemas/person.schema.json
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
{
"title": "Person",
"title": "person",
"$id": "dogwood/person.schema.json",
"description": "A page describing a person, who may be a speaker or author of posts.",
"type": "object",
"properties": {
"title": {
Expand All @@ -14,7 +16,9 @@
},
"roles": {
"type": "array",
"title": "roles",
"items": {
"title": "role",
"type": "object",
"properties": {
"title": {
Expand Down
47 changes: 24 additions & 23 deletions ...s/frontmatter-validator/schemas/post.json → ...matter-validator/schemas/post.schema.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,26 @@
{
"title": "session",
"title": "post",
"$id": "dogwood/post.schema.json",
"description": "A post or session tied to a specific datetime and which has an author or speaker.",
"type": "object",
"$defs": {
"nameOrNames": {
"oneOf": [
{
"title": "name",
"type": "string"
},
{
"type": "array",
"title": "names",
"items": {
"title": "name",
"type": "string"
}
}
]
}
},
"properties": {
"title": {
"type": "string"
Expand Down Expand Up @@ -57,33 +77,14 @@
"type": "string"
},
"author": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
"$ref": "#/$defs/nameOrNames"
},
"speaker": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
"$ref": "#/$defs/nameOrNames"
},
"tags": {
"type": "array",
"title": "tags",
"items": {
"type": "string"
}
Expand Down
4 changes: 3 additions & 1 deletion ...ontmatter-validator/schemas/redirect.json → ...er-validator/schemas/redirect.schema.json
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
{
"title": "Redirect",
"title": "redirect",
"$id": "dogwood/redirect.schema.json",
"description": "A page that only redirects to an internal or external page.",
"type": "object",
"properties": {
"permalink": {
Expand Down
4 changes: 3 additions & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@
"validate:people": "node ./_tools/people-validator/index.js --srcdir=.",
"validate": "npm-run-all -p validate:*",
"fix:people": "node ./_tools/people-validator/index.js --fix=true --srcdir=.",
"fix": "npm-run-all -p fix:*"
"fix": "npm-run-all -p fix:*",
"docs": "mkdir -p ./docs && jsonschema2md -h=0 -f yaml -o ./docs -x ./docs -d ./_tools/frontmatter-validator/schemas"
},
"devDependencies": {
"@adobe/jsonschema2md": "^8.0.2",
"filenamify-url": "^3.1.0",
"follow-redirects": "^1.15.3",
"gray-matter": "^4.0.3",
Expand Down

0 comments on commit e4afb03

Please sign in to comment.