I started playing with the 'javasphinx' project to see if it would work for generating the API docs.
So here is the basic idea of what it produces. I created docs for the following cloudstack directory: 'api/src/org/apache/cloudstack/api/' I then took the RST files and generated the html docs from it. I got a lot of errors like the following when trying to build the html docs with 'sphinx-build': ERROR: Unknown directive type "java:package" ERROR: Unknown directive type "java:import ERROR: Unknown directive type "java:type" ERROR: Unknown directive type "java:constructor" ERROR: Unknown directive type "java:method" etc... I am not sure if this is a long term issue, but we will probably have to solve other bigger problems first. For example, here is the RST output for the CreateNetwork command for an Admin: .. java:import:: org.apache.log4j Logger .. java:import:: org.apache.cloudstack.api APICommand .. java:import:: org.apache.cloudstack.api ApiConstants .. java:import:: org.apache.cloudstack.api ApiErrorCode .. java:import:: org.apache.cloudstack.api Parameter .. java:import:: org.apache.cloudstack.api ResponseObject.ResponseView .. java:import:: org.apache.cloudstack.api ServerApiException .. java:import:: org.apache.cloudstack.api.command.user.network CreateNetworkCmd .. java:import:: org.apache.cloudstack.api.response NetworkResponse .. java:import:: com.cloud.exception ConcurrentOperationException .. java:import:: com.cloud.exception InsufficientCapacityException .. java:import:: com.cloud.exception ResourceAllocationException .. java:import:: com.cloud.network Network CreateNetworkCmdByAdmin ======================= .. java:package:: org.apache.cloudstack.api.command.admin.network :noindex: .. java:type:: @APICommand public class CreateNetworkCmdByAdmin extends CreateNetworkCmd Fields ------ s_logger ^^^^^^^^ .. java:field:: public static final Logger s_logger :outertype: CreateNetworkCmdByAdmin Methods ------- execute ^^^^^^^ .. java:method:: @Override public void execute() throws InsufficientCapacityException, ConcurrentOperationException, ResourceAllocationException :outertype: CreateNetworkCmdByAdmin getVlan ^^^^^^^ .. java:method:: public String getVlan() :outertype: CreateNetworkCmdByAdmin I have also attached the themed output for this doc... Obviously, this is not enough detail for us to use for actual API documentation. If we wanted to go with this sort of documentation, we would need to really look at how the details are being discovered... Do any of you have ideas or suggestions on this front? Cheers, Will On Fri, May 30, 2014 at 4:33 PM, Sebastien Goasguen <run...@gmail.com> wrote: > > On May 30, 2014, at 4:25 PM, Will Stevens <wstev...@cloudops.com> wrote: > > > By clean install you mean starting from scratch, not 'mvn clean install' > > right? I have been doing mvn clean installs… > > > > Will, quickly stated I think that piece of code is a nightmare + folks > have complained about our apidocs. > > Since you are familiar with sphinx now, maybe you can give a try with: > http://bronto.github.io/javasphinx/ > > Create some brand new api docs …that we can build automatically like the > regular docs. > > 2 cts > > > Will > > > > > > On Fri, May 30, 2014 at 4:22 PM, Rohit Yadav <bhais...@apache.org> > wrote: > > > >> Hi Will, > >> > >> Based on my last memories of the apidocs tool and maven poms, I think it > >> used to scan built jar artifacts and reference them against something > like > >> a properties file (commands.properties?) and internally scans bunch of > >> annotations in available class files to find apis and create apidocs. > The > >> ApiDiscovery plugin uses the same approach to discover available apis > but > >> during load time instead of build time. > >> > >> I would also recommend a clean install in case there are any caching > >> issues. See if this helps. > >> > >> Regards. > >> > >> > >> On Sat, May 31, 2014 at 1:14 AM, Will Stevens <wstev...@cloudops.com> > >> wrote: > >> > >>> Hey All, > >>> Paul Angus and I have both tested this and this is what we are seeing. > >>> > >>> When we compile the the 'master' branch, the docs in > >>> 'tools/apidoc/target/xmldoc/html', but they appear to be the wrong > docs. > >>> Yes, we know that the versions that appear in the output is hardcoded > in > >>> the XSL files, but that is not what we are using as our reference. > >>> > >>> So in the 'tools/apidoc/pom.xml' the 4.4.0-SNAPSHOT is referenced. I > >> have > >>> also confirmed that when a build is done, the > >> 'tools/apidoc/log/@AGENTLOG@ > >>> ' > >>> shows that the > >> 'client/target/cloud-client-ui-4.4.0-SNAPSHOT/WEB-INF/lib/' > >>> directory is being referenced. > >>> > >>> However, when I check the 'tools/apidoc/target/commands.xml', it does > not > >>> include API calls which were added in 4.3 (I can verify with the > >> published > >>> 4.3 API docs). Also, the docs that are generated in the > >>> 'tools/apidoc/target/xmldoc/html' directory also does not have the API > >>> calls that were added in 4.3. > >>> > >>> I am stumped as to how this is happening. It is almost like the > >>> 4.4.0-SNAPSHOT is actually the 4.2.0-SNAPSHOT, but I am not sure how > that > >>> would be possible. > >>> > >>> If someone who understands this piece of the software can have a look > and > >>> verify what we are seeing, we would appreciate the insight... > >>> > >>> Thanks, > >>> > >>> Will > >>> > >> > >
