ept / avrodoc Goto Github PK

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, 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.

Hi!

I am getting sys.puts is not a function here because it was deprecated in newer versions of node.

Thanks

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
  } ]
}

The following functionality still needs implementing:

• 'oneway' messages: http://avro.apache.org/docs/current/idl.html#define_messages
• ordering and numbering annotations: http://avro.apache.org/docs/current/idl.html#minutiae_annotations
• omit the errors section if it's empty
• default values for fields

We are working on this and will open a pull request for this soon.

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.

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:

• Add a '+/-' symbol to the left of each that would expand or collapse the navigation section
• Make the actual labels for the headers clickable to navigate to their appropriate 'index' pages (see #11 for index page for types)

DEFAULT behavior for generated docs: all sections expanded and protocol index page displayed

Fields and named types can have aliases. We should display them somewhere.

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.

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).

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

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.

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

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

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.

Currently we have an embarrassing lack of tests!

• Jasmine is good for unit tests.
• Sauce Labs offer free Selenium testing for open source projects

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?

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

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.

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?