Page MenuHomeSoftware Heritage

build developer documentation for swh-graph
Closed, ResolvedPublic

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 triaged this task as Normal priority.Jul 9 2019, 5:02 PM
zack created this task.
haltode added a comment.EditedJul 16 2019, 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.Jul 16 2019, 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.

What was tried so far:

  1. Using Sphinx html_static_path. Problem: it cannot copy the whole folder as is, and only outputs the content of the javadoc folder in _static.
  2. Using Sphinx html_extra_path. Problem: same as above, expect now it is scattered in the root build directory.
  3. Using Sphinx extension rawfiles. Problem: cannot control where the folder is copied (it defaults to the swh-graph/docs folder...).

The asset generation inside swh-graph is easy to add, however moving the generated javadoc folder to the right Sphinx location without simply adding a cp command in the swh-docs Makefile seems a bit complicated with current setup. We need a generic way of adding files/folder in the swh-docs build directory, I'll try to investigate on how to implement this in the next few days.

haltode removed haltode as the assignee of this task.Sun, Aug 25, 2:55 PM
zack closed this task as Resolved.Mon, Aug 26, 10:28 AM
zack claimed this task.