Generate documentation from zipkin-api Thrift definitions

[abesto]

This PR uses the built-in Thrift html generator to generate documentation from the Thrift source files in zipkin-api. Since there are two source files, and there may be more in the future, we have two choices. One, generate separate sites for each source file. Two, generate a dummy wrapper Thrift source file that references all the modules, and generate a single documentation site that contains all the modules. The PR currently implements the latter option, but is easy to adopt for the other one if that's preferred.

I'm guessing some extra content might be nice, like adding when the document was generated, and for which version. Maybe even versioning it along with the API. But I think it's a good first step towards openzipkin/zipkin-api#21.

Expand for screenshot of the doc page for zipkinCore.thrift

[codefromthecrypt]

Nice find!

…

On Mon, Jan 29, 2018 at 12:20 AM, Zoltán Nagy ***@***.***> wrote: This PR uses the built-in Thrift html generator to generate documentation from the Thrift source files in zipkin-api. Since there are two source files, and there may be more in the future, we have two choices. One, generate separate sites for each source file. Two, generate a dummy wrapper Thrift source file that references all the modules, and generate a single documentation site that contains all the modules. The PR currently implements the latter option, but is easy to adopt for the other one if that's preferred. I'm guessing some extra content might be nice, like adding when the document was generated, and for which version. Maybe even versioning it along with the API. But I think it's a good first step towards openzipkin/zipkin-api#21 <openzipkin/zipkin-api#21>. Expand for screenshot of the doc page for zipkinCore.thrift [image: screencapture-file-c-users-abesto-appdata-local-lxss-home-abesto-zipkin-api-thrift-gen-html-zipkincore-html-1517156274858] <https://user-images.githubusercontent.com/59982/35484365-33077a4a-044f-11e8-888d-043331686945.png> ------------------------------ You can view, comment on, or merge this pull request online at: #98 Commit Summary - Generate documentation from `zipkin-api` Thrift definitions File Changes - *A* generate_docs_from_thrift.sh <https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-0> (15) - *A* public/thrift/index.html <https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-1> (51) - *A* public/thrift/style.css <https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-2> (184) - *A* public/thrift/wrapper.html <https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-3> (16) Patch Links: - https://github.com/openzipkin/openzipkin.github.io/pull/98.patch - https://github.com/openzipkin/openzipkin.github.io/pull/98.diff — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#98>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAD6170RlHQRx_D-Row8_NgHZSy9Hxb6ks5tPJ41gaJpZM4RvwLB> .

[codefromthecrypt]

When linking we should probably be very loud about "v1" eventhough the tags like http.url are the same. Maybe v1 in the http path or something..

[abesto]

Tried to pimp out the contents a bit with a quick XSLT transform. Turns out the HTML generated by Thrift is not valid XML. So if we want to modify the content, we'll need some more heavy-handed approach (like, Python or something). Or at least first tidy up the HTML before feeding it through XSLT.

Update: tidy (http://www.html-tidy.org/) plus the Saxton XSLT transformer look like they'll work.

[abesto]

How about this? Now both the <title> and <h1> of index.html (but not the other pages) loudly say V1, the URL path contains v1, and the fake wrapper module is gone from index.html.

[codefromthecrypt]

loud n clear. thanks for doing this!

[codefromthecrypt]

need to run this again as we added a constant. osx no likey. I changed to greadlink for a quick attempt, but it died later..

$ generate_thrift_v1_docs/generate.sh 
++ greadlink -f generate_thrift_v1_docs/generate.sh
+ me=/Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs/generate.sh
+ '[' 0 -gt 0 ']'
+++ dirname /Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs/generate.sh
++ cd /Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs
++ pwd -P
+ mydir=/Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs
+++ dirname /Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs
++ cd /Users/acole/oss/openzipkin.github.io
++ pwd -P
+ rootdir=/Users/acole/oss/openzipkin.github.io
+ target_root=/Users/acole/oss/openzipkin.github.io/public
+ target_dir=/Users/acole/oss/openzipkin.github.io/public/thrift/v1
+ rm -rfv /Users/acole/oss/openzipkin.github.io/public/thrift/v1
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/zipkinDependencies.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/wrapper.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/style.css
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/zipkinCore.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1
+ mkdir -p /Users/acole/oss/openzipkin.github.io/public/thrift/v1
++ mktemp -d
+ cd /var/folders/9g/60hsfdh12d364162635sjkwr0000gn/T/tmp.vzFaf8uU
+ git clone https://github.com/openzipkin/zipkin-api.git
Cloning into 'zipkin-api'...
remote: Counting objects: 255, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 255 (delta 2), reused 1 (delta 0), pack-reused 249
Receiving objects: 100% (255/255), 1.18 MiB | 451.00 KiB/s, done.
Resolving deltas: 100% (120/120), done.
+ cd zipkin-api/thrift
+ rm -fv wrapper.thrift
+ for source in '*.thrift'
+ echo 'include "zipkinCore.thrift"'
+ for source in '*.thrift'
+ echo 'include "zipkinDependencies.thrift"'
+ thrift -r --gen html -I . -out /Users/acole/oss/openzipkin.github.io/public/thrift/v1 wrapper.thrift
+ set +e
+ tidy -indent -asxml -output /Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.tidy.html /Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.html
line 1 column 1 - Warning: missing <!DOCTYPE> declaration
line 6 column 74 - Warning: missing <tr>
line 10 column 7 - Warning: discarding unexpected </code>
line 44 column 1 - Warning: discarding unexpected </code>
line 50 column 7 - Warning: discarding unexpected </code>
line 6 column 1 - Warning: <table> lacks "summary" attribute
Info: Document content looks like XHTML 1.0 Strict
6 warnings, 0 errors were found!


The table summary attribute should be used to describe
the table structure. It is very helpful for people using
non-visual browsers. The scope and headers attributes for
table cells are useful for specifying which headers apply
to each table cell, enabling non-visual browsers to provide
a meaningful context for each cell.

For further advice on how to make your pages accessible
see http://www.w3.org/WAI/GL. You may also want to try
"http://www.cast.org/bobby/" which is a free Web-based
service for checking URLs for accessibility.

To learn more about HTML Tidy see http://tidy.sourceforge.net
Please send bug reports to html-tidy@w3.org
HTML and CSS specifications are available from http://www.w3.org/
Lobby your company to join W3C, see http://www.w3.org/Consortium
+ tidy_status=1
+ '[' 1 -gt 1 ']'
+ set -e
+ java -jar /usr/share/java/Saxon-HE.jar -s:/Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.tidy.html -xsl:/Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs/transform.xslt -o:/Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.baked.html
Error: Unable to access jarfile /usr/share/java/Saxon-HE.jar

[abesto]

Right. I didn't do a great job documenting the requirements, esp. not on checking them. I guess a Docker container that can run this would be ideal at some point, but for now I'm just gonna re-run this from the same env.