Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add JSON schemas to AsciiDoctor output. #1907

Merged
merged 2 commits into from
Nov 24, 2020
Merged

Add JSON schemas to AsciiDoctor output. #1907

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
87cb6b0
Add JSON schemas to AsciiDoctor output.
emackey Nov 24, 2020
7d0f07f
Add the words PREVIEW DRAFT since this is not final yet.
emackey Nov 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,7 @@
*.nupkg
specification/.project
.DS_Store
specification/2.0/PropertiesReference.adoc
specification/2.0/JsonSchemaReference.adoc
specification/2.0/Specification.html
specification/2.0/Specification.pdf
13 changes: 6 additions & 7 deletions specification/2.0/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,18 @@ all: $(TARGETS)

# Generate the Properties Reference section of the spec from JSON schema.
# This uses 'npx' to minimally install the 'wetzel' tool, if needed.
# While the schema used by wetzel is the locally installed version, it
# generates inline links to the schema under $(SCHEMALINK), typically
# the canonical schema in the github default branch.
# When using embedded schemas, SCHEMALINK should be a relative path.

WETZEL = npx wetzel
SCHEMALINK = https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/schema
SCHEMALINK = schema
EMBEDSCHEMA = JsonSchemaReference.adoc

# Base name of the generated properties reference file
PROPREF = PropertiesReference
# Schema files to leave out of $(PROPREF)
IGNORESCHEMA = '["gltfchildofrootproperty.schema.json", "gltfid.schema.json", "gltfproperty.schema.json"]'
$(PROPREF).adoc: $(wildcard schema/*.json)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would add $(EMBEDSCHEMA) to targets here. Might want some sort of npx dependency too, but I'm not sure how that would work since the wetzel files are pulled from a remote.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think in the next round of changes I'm going to add the version number onto the end of wetzel. Specifically, something like this:

WETZEL = npx wetzel@0.1.0-dev.1.2

That way, updates to new versions of wetzel must be manually done in the Makefile, not just pulled in automatically whenever someone publishes. This would provide more stability of the history, for example pulling an old commit and re-running the old documentation would use the specific version of wetzel available at that point in history, and should exactly regenerate what the docs were back then. Likewise, changes to the docs introduced by new wetzel versions could be found with bisect, etc.

$(WETZEL) -n -a=cqo -m=a -p "$(SCHEMALINK)" \
$(WETZEL) -n -a=cqo -m=a -p "$(SCHEMALINK)" -e "$(EMBEDSCHEMA)" \
emackey marked this conversation as resolved.
Show resolved Hide resolved
-i $(IGNORESCHEMA) \
schema/glTF.schema.json > $@

Expand All @@ -33,12 +32,12 @@ SPECDEPS = $(SPEC).adoc PropertiesReference.adoc
$(SPEC).html: $(SPECDEPS)
$(ASCIIDOCTOR) -b html5 $(SPEC).adoc -o $@

# :allow-url-read: is necessary for the imbedded render.githubusers.com
# :allow-url-read: is necessary for the embedded render.githubusers.com
# math images to be processed for the PDF target. See
# https://github.com/asciidoctor/asciidoctor-pdf/issues/369
$(SPEC).pdf: $(SPECDEPS)
$(ASCIIDOCTOR) -b pdf -a allow-uri-read -r asciidoctor-pdf $(SPEC).adoc -o $@

GENERATED = $(PROPREF).adoc $(TARGETS)
clean:
-rm -f $(GENERATED) $(TARGETS)
-rm -f $(GENERATED) $(TARGETS) $(EMBEDSCHEMA)
emackey marked this conversation as resolved.
Show resolved Hide resolved
14 changes: 7 additions & 7 deletions specification/2.0/Specification.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@

// :regtitle: is explained in
// https://discuss.asciidoctor.org/How-to-add-markup-to-author-information-in-document-title-td6488.html
= glTF 2.0 Specification (Last Updated June 9, 2017)
= glTF{tmtitle} 2.0 Specification - PREVIEW DRAFT
:tmtitle: pass:q,r[^™^]
:regtitle: pass:q,r[^®^]
The Khronos{regtitle} glTF{tmtitle} Working Group
The Khronos{regtitle} 3D Formats Working Group
:data-uri:
:icons: font
:toc2:
Expand Down Expand Up @@ -52,7 +52,7 @@ Khronos 3D Formats Working Group and Alumni
* Scott Nagy, Microsoft
* Marco Hutter, Individual Contributor
* Uli Klumpp, Individual Contributor
* Ed Mackey, Individual Contributor
* Ed Mackey, Analytical Graphics, Inc.
* Don McCurdy, Google
* Norbert Nopper, UX3D
* Fabrice Robinet, Individual Contributor (Previous Editor and Incubator)
Expand Down Expand Up @@ -2048,11 +2048,11 @@ include::PropertiesReference.adoc[]


[appendix]
[[appendix-a-tangent-space-recalculation]]
= Tangent Space Recalculation

*TODO*
[[appendix-a-json-schema-reference]]
= JSON Schema Reference

// Generated with wetzel
include::JsonSchemaReference.adoc[]

[appendix]
[[appendix-b-brdf-implementation]]
Expand Down