search

dexX7 / java-libbitcoinconsensus

JNA binding and Java wrapper for libbitcoinconsensus
Other
9 stars 3 forks source link

Publish documentation and Javadoc #14

Closed dexX7 closed 8 years ago

dexX7 commented 8 years ago

The documentation should be published, at least everytime a release is tagged.

This might be done via Travis:

http://docs.travis-ci.com/user/deployment/#Conditional-Releases-with-on%3A

dexX7 commented 8 years ago

I'd prefer GroovyDoc over JavaDoc, although I noticed the GroovyDoc doens't pick up the enum constants of the script VerifyFlags (when run via IntelliJ).

msgilligan commented 8 years ago

I used GroovyDoc instead of JavaDoc for OmniJ because it can be used for both Groovy and Java source code and produce a single set of docs. Unfortunately, GroovyDoc has an out-of-date Java parser and doesn't work with several Java 7 features. It also doesn't support the AsciiDoclet plugin which I'm using in bitcoinj-addons. It really needs an update.

Why do you prefer GroovyDoc over JavaDoc for Java source code?

dexX7 commented 8 years ago

Why do you prefer GroovyDoc over JavaDoc for Java source code?

For Java source code JD is probably the better choice, but since we have Java and Groovy code, it would be nice to combine both.

I would recommend publishing to Github pages over AWS S3 because it's free. [from the other thread]

Thanks for the tip about GitHub pages! :)

I resolved the initial issue more or less:

  1. a new GitHub API access token was created
  2. the access token is set as secure environment variable via Travis
  3. a deploy script generates the docs, then initializes a new repo locally, and force pushes to gh-pages
  4. the script is executed by Travis (if not a pull request, and only for one build target, to avoid pushing four times)

For now, the docs for the latest commit are generated, but it would also be possible to publish the docs only for releases.

The "clear, re-create, and force push" approach is a bit awful in my opinion, so ideas for improvements are very welcome. :)

I'm not sure how you create the gh-pages for bitcoinj-addons, but if it's possible to wrap the generation into a script, then I could help you to setup Travis in a similar fashion. (it's really simple actually)

msgilligan commented 8 years ago

since we have Java and Groovy code

Well, typically, sites don't publish Java/Groovy Docs for their test code and the public API for this project is all written in Java.

I resolved the initial issue more or less

Really, cool, @dexX7 ! I need to check this out and learn more about Travis.

For now, the docs for the latest commit are generated, but it would also be possible to publish the docs only for releases.

It would be nice to have docs available for latest commit as well as the latest (or all) release(s).

I'm not sure how you create the gh-pages for bitcoinj-addons, but if it's possible to wrap the generation into a script

It's in a script. Let's create an issue over there for making it work with Travis.

Update: Issue https://github.com/msgilligan/bitcoinj-addons/issues/11 created.