Page MenuHomeSoftware Heritage

build developer documentation for swh-graph
Open, NormalPublic

Description

We need to generate the developer doc for both the Java and Python parts of swh-graph.

The Python part should be business as usual.
The Java part should be built with Maven (mvn site). To that end we should:

  • write such doc!… as it doesn't seem to exist yet :-)
  • figure out how to integrate the maven-built doc with our sphinx-based documentation pipeline. sphinx-maven-plugin seems the way to go, but I haven't explored it much yet

Event Timeline

zack created this task.Tue, Jul 9, 5:02 PM
zack triaged this task as Normal priority.
haltode added a comment.EditedTue, Jul 16, 3:58 PM

From the sphinx-maven plugin documentation :

The sphinx-maven-plugin looks for .rst files in the folder structure provided as part of plugin configuration within your pom file.

The plugin is not used to convert javadoc with Sphinx, but to add Sphinx-like external documentation to a Java project.

The only project I could find to achieve javadoc -> Sphinx is javasphinx however it is not maintained anymore.

zack added a comment.Tue, Jul 16, 4:06 PM

*SAD TROMBONE*.

Oh well, let's just make sure the JavaDoc can be built locally upon a dedicated make something invocation (or whatever).
Once we have that, we can instruct sphinx to run maven, and then ship the javadoc-generated doc as static assets that sphinx will just ship somewhere under docs.s.o.