I'm looking for a way to convert the javadocs from my open source project (generated in Eclipse) to GitHub MarkDown, or come up with some other simple solution to display my documentation on GitHub (shy of simply adding a docs directory). Is there a simple solution for this? Can I simply point the GitHub README.md to my docs directory? Is there something more elegant? I have been striking out on Google.
I don't think it's possible to make a usable Javadoc with MarkDown. The best solution is probably to commit the Javadoc you generated on the gh-pages branch (or in the docs/ directory depending on the settings of your project). It will be available at :
http://username.github.io/projectname
Here is an example from one of my projects:
http://ebourg.github.io/jsign/apidocs/
Currently you can also host your Javadoc with Github Pages from not only a gh-pages branch, but directly from the /docs folder within your master branch. You can check the help section on this topic, here (also check attached image below).
Also, there's a project on Github that targets some conversion of Javadoc to Markdown (have not tried it yet, just leaving the reference).
Do NOT check Javadocs into the source control for your project
Especially not into the master branch! I followed the other answers to this question for about a year before deciding it was a really bad idea. Why?
It made it too difficult to review diffs. I even made a script (see below) to update only the Javadoc pages that substantially changed, but it still was a mess.
It fooled IntelliJ's refactoring tools. I just tried to change .x() to .getX() and had to approve/reject every "x" in the Javadocs. Maybe I forgot to exclude the folder in IntelliJ, but if you ever use sed/grep/find on your project, you have to remember to exclude it every time.
It adds a bunch of data in git that just shouldn't be there, potentially making pull and clone commands take longer... FOREVER! Even if you later "remove" the folder, it's still stored in git.
Where should javadocs go?
It's probably best to post them on https://javadoc.io/, your web site, or AWS or heroku. If you must check javadoc into source control, make a separate project just for Javadocs so you'll never need to look at the diff. You can follow other people's answers for how to do this.
"I read your post, but I'm doing it anyway"
Here's my script to update fewer javadocs. It only copies files with substantial changes from the target/apidocs folder to the docs/apidocs folder. It also adds new files and deletes no longer used ones. I think I used poor names, newfile and oldfile, but it works. I mean, it wasn't enough to justify checking javadoc into my project's source control, but it helps.
#!/usr/bin/env bash
# -I means ignore lines matching a regular expression
# -q means "quiet" - only tell whether files differ or not
# -r means "recursive" - explore subdirectories
# -N means "treat absent files as empty" which makes absent files show up in Quiet mode.
diff -I '<!-- Generated by javadoc ' \
-I '<meta name="date" content="' \
-I '<title>' \
-I 'parent.document.title=' \
-N \
-qr \
docs/apidocs/ target/apidocs/ > target/javadocPatch.txt
# Now read in the output file created by the previous command and
# Update only files that have substantial changes.
while read ignore1 oldfile ignore2 newfile ignore3
do
if [ ! -f "$oldfile" ]
then
echo "Added $oldfile"
echo -n >$oldfile
cp -fu $newfile $oldfile
elif [ ! -f "$newfile" ]
then
echo "Deleted $newfile"
rm $newfile
else
echo "cp -fu $newfile $oldfile"
cp -fu $newfile $oldfile
fi
done < "target/javadocPatch.txt"
It might be a bit off topic but I believe what OP is looking for is a mechanism to automatically make javadoc available as a new version of the project is published.
If this is the case, then you can try: http://javadoc.io
It's a free service hosting javadocs for open source project, currently supporting maven central and bintray (jcenter).
You can generate a link to the latest version of your project. For example, this link https://javadoc.io/doc/org.springframework/spring-core always point to the latest version of spring-core, which is 5.2.0.RELEASE at the time I write this answer.
Declaimer: I run javadoc.io
Related
I have ElementaryOS installed. I am running Processing IDE in the terminal by running ./processing in the processing-3.3.4 directory. I'm getting this error:
java: error while loading shared libraries: libjli.so: cannot open shared object file: No such file or directory
This is a known issue that is being worked on. As of this moment, it doesn't look like they have released a fix, so I would try the previous version.
In the future, I recommend searching with Google for the specific error you're getting before posting to a forum. It can be hard to know what to search for, so here's an explanation of my process.
First I tried searching for "elementary os" processing cannot open shared object file "libjli.so" but since that didn't give me anything obvious, I assumed that this is not a widespread problem with Elementary OS. Note that I put quotes around "elementary os" and "libjli.so". This ensures that Google treats these as phrases, so pages with the word "elementary" and the word "os" will not match unless those two words are side-by-side.
Next I searched for processing ide cannot open shared object file "libjli.so" which gave me a link to the main Issues page on the github project. On that page, I searched for libjli.so which gave me one result, which is the issue I linked here.
I hope that helps you in the future.
Download Java SE Development Kit 8u192 in your home directory (click "Accept License Agreement")
Extract (in terminal):
tar xzvf ~/jdk-8u192-linux-x64.tar.gz
Create the symbolic links:
sudo ln -s -f ~/jdk1.8.0_192/bin/* /usr/bin/
Test:
java -version
I'm a total Java noob so please understand =) I need a quick advice on how to fix the issue.
I cloned the official selenium git repo, changed the code a bit (need to dump the page into some specified dirs), and tried to rebuilt it:
./go //java/server/src/org/openqa/selenium/remote/server:server:uber //java/client/src/org/openqa/selenium:client-combined:uber
It was successful but when I tried to execute it I got this:
$ java -jar build/java/server/src/org/openqa/selenium/remote/server/server-standalone.jar
Failed to load Main-Class manifest attribute from
build/java/server/src/org/openqa/selenium/remote/server/server-standalone.jar
Tried to check classpath, CLASS_PATH and CLASSPATH env variables (as a friend of mine suggested) - I simply don't have any.
At the same time, the pre-compiled standalone server from the official downloads works out of the box.
The official docs didn't help. There's nothing about it there.
So - I need a quick advice how to compile it? Thanks.
P.S. JDK 8 (latest), Mac OS 10.7
P.P.S. That friend of mine tried to build it by himself and he was lucky - he got a new build/dist folder where the target big file was. But in my case, the build folder is created, but there's not 'dist' folder in it.
Finally found the answer: I should have built it like that:
./go clean release
it's really strange that all the docs state I need to use these long /bla/bla/:uber things to get a whole single 'uber' server.
tl;dr JGit's checkout throws exceptions while command line git checkout works fine
I'm currently trying to use JGit to check out certain revisions from an online Git repository, in Java (for work). My current approach is (and I'm very new to Git, coming from a SVN background, so this may be wrong):
clone the repository to a temporary location on my hard drive
figure out which revision I want, (I have tried using the SHA-1 hash as well as the name of a branch)
checkout that revision
from there, I would be using the checked out files as inputs to a later part of the program.
checkout a different revision
use those files as inputs to another part of the program
Essentially, I want to be able to swap the contents of my temp folder with whichever revision. With the command line interface I've been able to do this with git checkout master and git checkout dylanbranch (where dylanbranch is a branch I made on my own clone with an arbitrarily chosen revision), but my Java code attempting to do the same thing fails:
Git git = Git.open(new File("checkout")); //checkout is the folder with .git
git.checkout().setName("master").call(); //succeeds
git.checkout().setName("dylanbranch").call(); //fails
And the exceptions printed to the console:
Exception in thread "main" org.eclipse.jgit.api.errors.JGitInternalException: Checkout conflict with files:
src/sizzle
test/qunit
at org.eclipse.jgit.api.CheckoutCommand.call(CheckoutCommand.java:211)
at com.avi.scm.git.BranchCheckout.main(BranchCheckout.java:30)
Caused by: org.eclipse.jgit.errors.CheckoutConflictException: Checkout conflict with files:
src/sizzle
test/qunit
at org.eclipse.jgit.dircache.DirCacheCheckout.checkout(DirCacheCheckout.java:387)
at org.eclipse.jgit.api.CheckoutCommand.call(CheckoutCommand.java:162)
... 1 more
I can verify that the files in question are marked as deleted and not staged for commit by using git status though I'm not sure why those changes are there, and they come back any time I switch back to the master branch. Despite that, I can still successfully change the working tree with command line Git.
So my question: Why won't JGit work for this application when command line git will?
Any other helpful information is appreciated- educate me :)
Update I've been testing with the jQuery repository, and have noticed a few more problems with JGit: When I am working with the "master" branch, git status temms me that I'm #On branch master and that there is nothing to commit (working directory clean), but using JGit's status command I see that test/qunit and src/sizzle are marked as Missing. JGit's reset seems to do nothing.
The two directories mentioned in the stack trace are Git submodules (test/qunit and src/sizzle) which is most likely the cause of the problem since JGit does not have full submodule support yet.
This may function differently in the 1.1 JGit release due out this month based on this commit.
You can read more about the current state of JGit submodule support here.
I know this doesn't directly answer your question, but I've also had problems with the Java implementations of Git. What worked best for me was to simply ditch the java implementations, and execute command-line calls to git from within the application. It may not be ideal, but it'll do exactly what you want since you'll fully control the command.
Simply call
Runtime.getRuntime().exec(...)
Link to Javadoc for Runtime class
I had a similar problem with Checkout. I think that the fact that you can switch branch with unstaged content in Git is actually a tolerance, not a feature.
JGit is globally not as tolerant as Git, so you should usually test many cases.
It seems it is not directly your problem (which is related to the submodules), but for more general cases you would want to commit your changes before using checkout to switch to another branch.
Note that the CheckoutCommand works perfectly for me to start a new branch from an old revision (you have to set the name of the branch and the start revision).
I'm trying to write an SVN Post-Commit hook to generate javadoc on a webpage whenever someone submits any changes to relevant files.
I was new to the hook concept, but I didn't expect to run in any strange errors when generating the javadoc.
java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImpl cannot be cast to com.sun.javadoc.AnnotationTypeDoc
at com.sun.tools.javadoc.AnnotationDescImpl.annotationType(AnnotationDescImpl.java:46)
at com.sun.tools.doclets.internal.toolkit.util.Util.isDeprecated(Util.java:811)
at com.sun.tools.doclets.formats.html.AbstractIndexWriter.printComment(AbstractIndexWriter.java:186)
After a few succesful searches on StackOverFlow I discovered it had something to do with third-party-annotations. (I make use of the Play framework and that uses a number of other libraries)
So I included everything in a script:
#!/bin/sh
CLASSPATH="~/Play/play-1.1.1/;"
javadoc -d ~/svndoc/ -classpath $CLASSPATH -sourcepath ~/svntest/avon/trunk/ScoreDB/app #packages
But this generates the exact same errors. Sometimes there are 10 warnings, but most of the time there are 27 of them.
Could you guys help me out?
Thanks in advance,
Jasper
Your classpath looks wrong. First, there should be no ; in it (in Unix, the separator is :, but it is not needed at the end). Secondly, do you really have the individual class files in this directory? If there are jar files, you need to either list them individually, or put a * there (but pay attention that bash does not expand it, since you would need : instead of spaces between).
I have no idea if this would solve the problem, though.
I'm trying out PMD on some Java source code.
I understand from the Terminal window on my Mac (Unix shell), the syntax is like so:
pmd.sh html|xml|text|vbhtml rulesetfile1[,rulesetfile2[,..]]
But the question is, what are the names rulesetfile1, 2 ... n...
I mean I've seen this list on the website:
http://pmd.sourceforge.net/rules/index.html
But how does this correlate to the comma separated list I can supply from running the shell command?
Can someone point me to a cross-reference so I can correlate the two?
Cheers.
This should be available in the ruleset folder of pmd installation. Here is the link to the folder in PMD's source repository.