How to create Sphinx-based documentation in a Jython project? - java

I'm working on several Jython projects using libraries written in Java. I'd like to create some good documentation with Sphinx thanks to the autodoc extension. However when I try to create the html, I get errors because autodoc can't find the libraries written in Java:
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.0.5
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index
/Users/myName/myJythonProject/doc/index.rst:14: (WARNING/2)
autodoc can't import/find module 'myJythonProject', it reported error:
"global name 'PoolManager' is not defined",
please check your spelling and sys.path
where PoolManager is a Java class.
Could anyone help me to solve this problem?

Sphinx can be used to document Jython projects, but autodoc does not work for code written in Java. The autodoc feature imports and inspects Python modules. There is no support for doing the same with Java classes.
Implementing autodoc (or something similar) for Java seems feasible, but someone has to volunteer to do it. See this comment by Sphinx author Georg Brandl: https://www.mail-archive.com/sphinx-dev#googlegroups.com/msg03162.html.
I found some information about a proposed GSoC 2010 project aiming at implementing multiple language support for autodoc. But according to this blog post, the project wasn't completed. The developer chose to work on another GSoC project.
The sphinx-contrib repository does not contain anything related to autodoc.
Update
There is a new Sphinx extension called javasphinx that looks interesting. I have not used this extension, but according to the documentation, it can produce reST sources from Java code:
The javasphinx-apidoc tool is the counterpoint to the sphinx-apidoc tool
within the Java domain. It can be used to generate reST source from existing
Java source code which has been marked up with Javadoc-style comments. The
generated reST is then processed alongside hand-written documentation by Sphinx.
javasphinx makes use of another library called javalang.
PyPI packages:
https://pypi.org/project/javasphinx/
https://pypi.python.org/pypi/javalang

Related

Java Development Workflow with Text-Editor and Commandline

I want to get started with Java! I have a bit of experience with C/C++ and Python development. For this i'm mainly using Emacs (a text editor) and the commandline, thus not using a heavier weight IDE for those kind of things.
I don't want to adapt my workflow to suit an IDE, but I don't know the Workflow (write, build, test) in Java so I thought about asking here. Searching the Web didn't give me good results.
Can someone give me the the basic workflow when developing Java with my requirements? I use Linux for all my programming.
Are my requirements/wishes even practical or should i consider using something like IDEA or Eclipse?
Can someone point me to documentation or blog posts about this topic or documents, that give a quick overview and/or examples on how to get started with Java (something for programmers with a little experience in other languages)?
For this I'm mainly using Emacs (a text editor) and the commandline,
thus not using a heavier weight IDE for those kind of things.
An IDE has many advantages over a text editor, mainly when navigating, debugging and refactoring code, but it is not required. Actually, working without an IDE is useful to understand the underlying technologies. My advice would be: Start without an IDE, and when everything works, try out some IDEs to see how they help you.
Can someone give me the the basic workflow when developing Java with
my requirements?
The basic workflow is (for any compiled language):
write source code
build
run
In the case of Java, that means:
1 Writing source code
You write .java files in a text editor, observing the right filesystem layout (file name = class name, directory corresponds to package etc.). You already have that covered.
2 Compiling the code
You compile the code using a Java compiler, possibly building a JAR or WAR file (depending on the type of application you are writing). You can do that manually by directly invoking javac (see for example Java - compile from command line - external jar ), but you should really use a build tool. The best tool to get started is probably Apache Maven or Gradle.
The basic idea is the same with both Maven and Gradle: You write a build file, which essentially describes your project and how to compile it (a POM file in the case of Maven, a build.xml for Gradle), then you can build by just invoking the build tool. The build tool takes care of all the nitty gritty like invoking javac etc. Most importantly, both also perform dependency resolution, meaning they can automatically download and use libraries that you use in your code.
3 Running
Finally, you run the program from the command line. How to do that depends on the type of program: A simple executable (or a Spring Boot application) can by run using java -jar myprog.jar, a WAR file must be deployed to a Servlet container (such as Apache Tomcat).
I hope this gives a general overview of How do I develop without an IDE?. For more details, look for specific questions here on Stackoverflow (or elsewhere), read the docs, and if all fails ask a more specific question here :-).
I agree with #sleske : if you really want to learn the language, it's good to start with a text editor. Later on you can use an IDE but by then you will know how the build process works and what exactly the IDE is doing. There exists no magic in coding. If something works but you don't understand why, it will certainly fail one day :)
Maybe some nice feature: I use Eclipse and added a vim plugin :)
And if you learn some useful shortcuts you can write code really fast (without a mouse)
You should download IntelliJ directly:
certain best practices like static import make your code more readable because you read it with a smart IDE. If you read code just with vim, the navigation between classes is not possible.
you have an easy access to a terminal and perform certain Maven or Gradle commands here.
I would not say the same with other languages (css, html).

Where is the documentation for Matrix Toolkits Java and Netlib-Java?

I set out to install some fast matrix and BLAS libraries for Java, and settled on MTJ (backed by netlib-java) based on the results of Java Matrix Benchmark. I believe I have everything installed via Maven, but I can't find any credible documentaiton for these libraries.
The logical starting point would be the github pages:
MTJ
netlib
...But I can't find a link to any tutorials or javadoc beyond the incredibly terse MTJ wiki section on Github. Netlib's source appears to be in fortran (with F2J as a compilation step) so I can't crawl directly though source in lieu of javadoc, either.
To make things even more baffling, there appears to be some sort of Javadoc for MTJ out there hosted by a German university for some reason, that references packages (like nni.BLAS) that don't appear to be part of the MTJ library that Maven made for me. There's another even sketchier Javadoc hosted somewhere inside the University of Tennessee that, while having no apparent connection to the netlib-java project, does somehow have a Javadoc page that seems to explain the three extra integer arguments that netlib-java's DGEMV implementation uses (offsets of some sort?). If I look at the fortran documentation inside the netlib-java distribution for DGEMV, it has the eleven standard arguments that I would expect from DGEMV.
So here are my questions:
1.) Is there official documentation for MTJ/netlib? If so, where?
2.) If there is no official documentation, are there any other resources out there that would allow someone to learn to use this library? If this project isn't used exclusively by the developers, then people are learning to use it somehow. How?
3.) If a Java version of netlib's 11-argument DGEMV isn't installed as part of MTJ via Maven, then what is this 14-argument thing on my hard drive?
Thanks.
If you download MTJ via Maven, you can also download the Javadoc and source jars at that time. (IntelliJ IDEA will do this for you automagically.) The jar is called mtj-1.0.2-javadoc.jar and contains comprehensive Javadoc. Once upon a time, this seemed to be available on a website, but that site seems to be gone.
The closest I've seen so far:
http://en.wikipedia.org/wiki/Matrix_Toolkit_Java
Here is link to jar archive with complete javadoc of latest stable MTJ. Just unzip it with tool such 7zip or similar. I agree that lack of guides related to this library might be dauting.
I have created a site for mtj 1.0.3-snapshot on divshot.io:
http://mtj103.divshot.io/
Hope this helps.

Integrating a Rascal project with a Java Project

I developed a code generator in Rascal and I want to integrate it with a tool developed in Java. I tried to generate a jar file for the Rascal project with eclipse to put into the Java project, but it just puts the Rascal files of the project into the jar. I searched into Rascal Tutor and here, but I didn't find nothing about it.
Someone knows how I can do this?
As of yet, this scenario is not that straightforward (also see discussion in github issue #57). In principle, it is possible to call Rascal from java, but you would have to construct the Evaluator and import modules and call functions, and do the translation from our IValues to your java data type.
For inspiration on how to initialize an Evaluator: https://github.com/cwi-swat/rascal-shell/blob/master/src/org/rascalmpl/shell/RascalShell.java
The other way around, might work more easily. It is easy to call a Java method in Rascal and adding your own menu option in a Java editor is also straightforward.

java Api catalog? komodoedit java auto complete feature

Hi by default komodo edit supports the following languages for its auto completion feature by default:
Ruby: require, class modules (on . and ::), class variables and methods, method calltips.
Python
Perl
PHP
XSLT
XML
Tcl
I am programming in java at the moment, and I need to have the auto completion feature with that language. Can someone please tell me where i can download it or how i can enable it. thank you in advance.
EDIT:
If i go to preferences, code intelligence, there is an option to add API catalog from my hard drive. so there must be a java api catalog? how can i get it?
Komodo's goal is to provide the same features than Java/.net IDE but this time for dynamic languages such as Perl, Python or Ruby. And as said in this post there is already a better integration of Java (or .net) in other specialized IDEs.
You should look at Eclipse, Netbeans or IntelliJ.

Practical Java - Development Environments

I've had several classes - university level - on Java.
However, what these classes lack is some practical approach to Java - or, to programming as a whole. Things you can only learn in a business.
However, since I am not allowed to use Java on the workfloor, I don't get to learn this now - even though I would like to.
So I guess what I'm asking for is any number of plain have-to-know Java resources. Things concering, for example, what Ant is and why and how to use it; using revision control systems from your IDE; standard Java libraries you would use often ... Anything that would help with actual software development, really.
As some side information, I've been using Eclipse for about four years now, and I feel at home there.
I have a system that works fairly well for class assignments and for projects as well. Firstly, I create one Eclipse project per class. This way I can re-use classes from previous assignments. You can also customize your classpath by adding another project as a library.
I use the Maven plugin for Eclipse M2Eclipse. Not only does this give you the ability to search for libraries and add them easily but the exec:java plugin is an easy way to execute your code from the command line. It's helpful because when it executes your code, it uses a classpath that includes all linked Maven dependencies. If you aren't using external libraries, you might not need Maven but I've found it to be helpful to learn in preparation for the job market. It's fairly simple to start with plus there are a ton useful plugins for open source projects.
Next, for revision control I recommend Subclipse. You can get a free SVN account with a single login from Unfuddle.com. Link that up to your Eclipse environment and Import your project.
When I want to get a particular class specification, I go to Sun's Java documentation.
Another excellent resource that will certainly give you the reference material (searchable!) to answer any java question would be this torrent containing ~100 ebooks on Java, sorted by directory on various topics (like Ant, Eclipse, or Swing).

Categories

Resources