ept / avrodoc Goto Github PK
View Code? Open in Web Editor NEWDocumentation tool for Avro schemas
License: Apache License 2.0
Documentation tool for Avro schemas
License: Apache License 2.0
In the navigation bar on the left-hand-side, there are headers currently for 'Protocols' and 'Types'. It would be nice to make these headers multi-purposed in the following ways:
DEFAULT behavior for generated docs: all sections expanded and protocol index page displayed
Hi!
I am getting sys.puts is not a function
here because it was deprecated in newer versions of node.
Thanks
Currently, there is a protocols index page that is displayed by default when you open an avrodoc file. It would be great to have a similar page specific to types. This way we could get a quick overview of all of the types, descriptions of the type, and a clickable link to each type.
avrodoc fails with "Not a valid json file: JdbcConfig.avsc" (the file is a valid json file though...) for the following schema:
{
"type" : "record",
"name" : "JavaConfig",
"namespace" : "org.spf4j.base",
"fields" : [ {
"name" : "io",
"type" : {
"type" : "record",
"name" : "IoConfig",
"fields" : [ {
"name" : "tmpdir",
"type" : [ "null", "string" ],
"doc" : "org/spf4j/base/Runtime.<clinit>:107",
"default" : null
} ]
},
"doc" : "Category: io"
}, {
"name" : "version",
"type" : [ "null", "string" ],
"doc" : "org/spf4j/base/Runtime.<clinit>:116",
"default" : null
}, {
"name" : "home",
"type" : [ "null", "string" ],
"doc" : "org/spf4j/base/Runtime.<clinit>:120",
"default" : null
} ]
}
For situations where you can't redirect stdout (e.g. some CI servers), we should support writing the HTML output to a file specified on the command line.
I think sort(1) is a good example for command line style. In its style, we would support all these forms (argument order doesn't matter, so the output argument can come before or after the inputs):
$ avrodoc input1.avsc input2.avsc > output.html
$ avrodoc input1.avsc input2.avsc -o output.html
$ avrodoc input1.avsc input2.avsc --output output.html
$ avrodoc input1.avsc input2.avsc --output=output.html
$ avrodoc -o output.html -- -input-file-that-starts-with-a-hyphen.avsc
Currently we have an embarrassing lack of tests!
The following functionality still needs implementing:
We are working on this and will open a pull request for this soon.
Hi,
I am planning to use avrodoc as part of the schema development process, is this project still maintained?
for and example of how I use this, please see: https://github.com/zolyfarkas/avro-schema-examples
let me know
thank you
I have a schema defined in AVDL which makes heavy use of backtick-delimited preformatted code blocks for ASCII art. Avrodoc does not interpret these correctly at all.
I think the problem is that they are a Github extension. Would they be difficult to support?
See Issue #11.
If the types page gets added, it would be nice to have an option when generating the avrodoc file to specify that the types index page should be set to the homepage rather than the protocols index page.
We have a number of generated avrodoc files that have a couple of empty protocol definitions that simply contain slews of type definitions. These are the docs we are shipping to customers and it would be nice to have them displayed at the homepage rather than having to click through to each type to get a glance of what is available to them.
As it is necessary in some projects to keep documentation for different versions it might be helpful for users to see information about build/generation time and schema version on the main page.
What if there is a label that display these information if relevant parameters were provided during build process?
Currently any errors during schema parsing are thrown as JavaScript exceptions and just bubble to the top. Unless the user has the JavaScript console open, all they see is a blank page. We should catch those errors and show them to the user (in a dialog box or something).
It appears that currently named types are processed in alphabetical order, so any nested type which has not yet been processed will fail due to the type not yet being defined.
I've solved a similar problem in my own repositories using the dependency-graph module and would be glad to contribute here.
Thoughts? If not, I'll begin work on the changes.
Fields and named types can have aliases. We should display them somewhere.
All idl objects (protocols, records, messages, errors, etc) that can be namespaced can also accept arbitrary attribute decorations.
idl can be decorated with these arbitrary attributes and the avro tools converter from idl to avro schema maintains these as top-level attributes under the specific record for either the protocol, record, message, etc.
Example (IDL):
@linksFrom("com.inome.testTypeA")
@linksTo("com.inome.testTypeB")
record EdgeAType { string property = ""; }
Example (Avro SCHEMA):
{
"type" : "record",
"name" : "EdgeAType",
"namespace" : "com.inome",
"doc" : "Some documentation.",
"fields" : [ {
"name" : "field1",
"type" : [ "null", "com.inome.X" ],
"doc" : "Some documentation",
"default" : null
} ],
"linksFrom" : "com.inome.testTypeA",
"linksTo" : "com.inome.testTypeB"
}
The output of this should go on the specific details page for each type of object. Probably as simply a separate table of key-value properties as the keys and values are just arbitrary strings. However, if a specific namespaced type is discovered in either place, an appropriate link should be generated.
In Firefox version 18, I've noticed that when you hover over a known complex type on a protocol page, if that type contains as a property another known complex type, the popover dialog flickers and is impossible to read.
I can't easily get a screenshot of this behavior but I'm using Firefox 18 on Ubuntu 10.4. I've tried at least FF 18 on Windows 7 and the issue doesn't appear there.
This is not a huge deal but something that could possibly be fixed for a future version.
Thanks,
Micah
There is a bug when generating the type definition pages that appears to be linked to a type definition having a complex member variable. When outputting these types (DateRange in the attached example), the definition is output numerous times rather than a single time with a list of protocols that define it.
Compare the output of Date and DateRange in the sample.html file from this gist: https://gist.github.com/mphuff/5461540
This Sample.html file was generated from this command: avrodoc ProtoclA.avsc ProtocolB.avsc ProtocolC.avsc --output=Sample.html
There is this example in the top-level readme file:
Take a look at the example, which is generated from
this schema.
When I visit http://avrodoc.herokuapp.com/#/, I see a 404 page from Heroku saying:
There's nothing here, yet.
Could be my problem, not sure, the install seemed to go okay.
The generated html file from my .avsc source is generated but then fails the render, the browser just seems to hang trying to load the file.
Thx,
Mike Sherman
Are decomposed Avro schemas are supported?
I have a large number of objects in a deeply nested object hierarchy and we've separated each object into its own avsc schema file. Leaf "objects" only have primitive types and non-leaf objects reference other objects rather than define them inline, like so:
{
"namespace": "my.namespace",
"type": "record",
"name": "TopRecord",
"fields": [
{"name": "Field1", "type": ["null", "string"], "default": null},
{"name": "Field2", "type": ["null", "string"], "default": null},
{"name": "Field3", "type": ["null", "string"], "default": null, "aliases": ["UpdateDtm"]},
{"name": "Field4", "type": ["null", {"type": "array", "items": "string"}], "default": null},
{"name": "Field5", "type": ["null", "SubRecord1"], "default": null},
{"name": "Field6", "type": ["null", {"type": "array", "items": "SubRecord2"}], "default": null}
]
}
where SubRecord1 and 2 are defined in their own schema files (and may reference other subrecords, etc.)
Is this model supported in AvroDoc? When I run:
avrodoc src/main/resources/avro/import/*.avsc > foo.html
It runs without error but when I load foo.html into a browser it just displays "Loading" in both Chrome and Firefox.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.