Evaluate Paradox as documentation solution (was: Remove code from documentation and link to example classes)

[lwhite1]

Code in docs is impossible to maintain.

[benmccann]

Maybe we could turn each page into a Jupyter notebook.

Here's an example. You can edit it and run it online by clicking "Execute on Binder" from nbviewer. It does take awhile to launch though https://nbviewer.jupyter.org/github/benmccann/nbviewer-test/blob/master/Tablesaw.ipynb

It would give us the following advantages:

• Viewable online with output. User doesn't need to download and run to see what it looks like
• Supports markdown. Will help make migration easier and allow for rich descriptions
• Can run online to ensure code works.
  • We would need to update periodically to use latest version of Tablesaw. It's relatively easy to identify breakages when upgrading because the code is runnable unlike our current markdown files
  • It's always clear to the user what version is being demonstrated. It may sometimes be on an old version if we haven't updated it, but it shouldn't ever be broken.

[benmccann]

You can also embed in sphinx as an alternative to nbviewer: https://nbsphinx.readthedocs.io/en/0.4.2/code-cells.html

[benmccann]

Something like Paradox which lets you embed Java in Markdown would be another alternative to ensure the code in the docs compiles

[lwhite1]

Paradox looks great. If the markdown is referencing code in a file that gets compiled and tested regularly, perhaps we're not doomed after all :)

[ryancerf]

I put in a half hearted effort trying to get paradox and sbt to work with maven and gave up.

I came to the conclusion that I would much rather write my own maven plugin that has similar snippet inclusion functionality rather than fiddle with build tools.

I got a proof of concept working pretty quickly and I think it could get the job done (I might also use it for other projects). It copies the docs directory to target and resolves snippets located in source files. It is almost exactly the same as Paradox's snippet inclusion feature, but that is all it does.

Let me know if you are interested and I can try to figure out how to upload it to maven so we could use it.

[benmccann]

Ah, yeah, I hadn't really thought about Paradox being primarily available as an SBT plugin.

The Paradox code looks pretty well structured. There's a separate module for the code Paradox stuff and then an SBT module that just has one file to invoke it from SBT. It looks like it'd be pretty feasible to make a Maven module that does the same thing. Most of the code is just passing options through, so I imagine an MVP could be fairly straightforward since you wouldn't need to support all the options from the beginning

See also https://github.com/lightbend/paradox/issues/236

[lwhite1]

@benmccann I'm not sure I understand. Are you suggesting @ryancerf add maven support to paradox rather than do his own thing?

What do we need from Paradox beyond code inclusion?

(I'm feeling anxious to fix our documentation and afraid that feeling will pass soon ;)

[benmccann]

I think it's worth considering. I haven't used either enough to fully understand the tradeoffs, but I wonder if we'd want to develop and maintain a documentation generator long-term. Paradox also offers things like automatic table of contents generation, advanced linking support (e.g. to make it easier to link to github or javadoc), and callouts.

[benmccann]

I took a look at creating a Paradox Maven plugin. The tricky thing seems to be that Paradox is written in Scala so you'd want to create the Maven plugin in Scala. I don't know a lot of Scala. I don't think it'd be hard if we could find a good example, but the only example I found was too outdated to work still

[benmccann]

It's probably easier to use @ryancerf's plugin since it sounds like he already has that working. I filed some requests with the scala-mojo-support project, but unless they get addressed I'm not sure I'd want to spend more time on that path

[ryancerf]

I do not mind Scala, but mixing build systems has never worked well for me in the past. Let's give my plugin a try (when it is done).

@lwhite1 Hold on to that desire to fix the docs. I should have something soon!

[benmccann]

I agree mixing build systems would be a bad idea. I was thinking more to write a Maven plugin that calls the core Scala code, which they've neatly separated from the SBT plugin. But not sure it's worth it since you've already got another solution basically working

[ryancerf]

Here is the plugin. I think it will work nicely for our limited needs.

I am having some trouble figuring out how to consume it. I tried using jitpack but was not able to get it to work. I dont really want to deal with uploading it to maven at the moment. Do you have any recommendations?

[benmccann]

Bintray is the other one I've seen. Uploading to Maven Central isn't too hard except they make you file a JIRA ticket and wait for someone to manually enable you which can make it take awhile to get started.

[benmccann]

GitHub just came out with a feature too, but looks like it might be only a waitlist for now? https://github.com/features/package-registry

[hmf]

@benmccann

Just to inform.

I took a look at creating a Paradox Maven plugin. The tricky thing seems to be that Paradox is written in Scala so you'd want to create the Maven plugin in Scala.

You don't have to know Scala. You can call Scala directly from Java. There are some caveats regarding java static classes and methods and type conversion but it's doable. You also have to make sure to add the Scala run-time library.

See for example:

• https://lampwww.epfl.ch/~michelou/scala/using-scala-from-java.html
• http://blog.muhuk.com/2016/05/24/how_to_call_scala_from_java__using_scala_classes.html#.XWFTxvwo_Q8

[benmccann]

While you can call Scala from Java, it's quite a pain. E.g. a big issue in this case is that Scala doesn't generate default constructors

[hmf]

@benmccann Apologies for the late reply (am on holiday 8-)).

Looked at the issue you refer to and the the links you provide. Note that the Stackoverflow question you refer to also points to the same link I gave you. There you find an example of setting the default parameters explicitly.

I may be missing something but why is it quite a pain (I think it may be easier than the this suggestion). As I see it you have 2 options:

• Use a builder that instantiates the Scala object explicitly setting the default values as shown here(last section).

• Use a facade that delegates to the Scala obtect. Same as above, only now you havs a set of constructors you can use directly.

If you want to checkout a branch with what you want/need I can try and help.

[benmccann]

Ah, I missed the second answer on StackOverflow because it had only two votes compared to the accepted answer with seven votes that said it's impossible.

In any case, @ryancerf has implemented his own pure Java replacement of Paradox. While it's less powerful, it has the snippet replacement functionality that we were mainly wanting. I'm not sure that we'd spend more time on implementing a Paradox Maven plugin at this point.

Thanks for the pointers!