On Jun 2, 2014, at 9:16 PM, Will Stevens <wstev...@cloudops.com> wrote:
> 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? > I got to the same stage as you, Might not be worth pursuing. I will try to contact some of the javasphinx-developer and see what they say. -sebastien > 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 > >>> > >> > > > <api_docs.png>
