Closed GoogleCodeExporter closed 9 years ago
I agree. JavaDocs—like binaries/bytecode—are a byproduct of the source code
and should be made during your own build.
I've been using "svn status | grep -v html", which is slightly annoying and
slightly dangerous.
Original comment by ThomasCR...@gmail.com
on 26 Nov 2010 at 8:28
I agree it's annoying for developers. I often find myself running svn commands
from within src, which is another slightly dangerous approach.
The upside is that checkign in the the javadocs makes them available on the web
at http://semanticvectors.googlecode.com/svn/trunk/doc/index.html (you need to
click "view raw file" to get them to render as html).
Is there a way to get this upside without checking in every artificial diff?
How do other projects keep their online javadoc up to date?
Original comment by widd...@google.com
on 27 Nov 2010 at 12:59
I have created the top directory javadoc in the svn: so the javadoc inside the
"trunk" directory (or any branches or tags for the software) can be removed
from SVN. Inside the javadoc dir, we can create one or more trees for the
javadoc for any version we want to have online (e.g. the versions available for
download or the current trunk etc.).
Everytime we want to update some javadoc tree I would suggest to just manually
copy update it with the modified htmls from what is generated in the non-svn
javadoc inside the software directory.
So the questions is: for which software versions would we want to have javadoc
trees available online? Reasonable candidates are in my view the current trunk
and the latest published release.
Original comment by johann.petrak@gmail.com
on 27 Nov 2010 at 4:27
I have created and checked in the javadoc for the 1.30 release:
http://semanticvectors.googlecode.com/svn/javadoc/1.30/index.html?overview-summa
ry.html
Original comment by johann.petrak@gmail.com
on 27 Nov 2010 at 5:53
Looks great.
I'm not pickup up the new javadoc directory when I run 'svn up', am I doing
something wrong with svn?
Should the old autogenerated doc directory be removed from svn at this point,
to avoid the excessive commits issue?
Original comment by widd...@google.com
on 28 Nov 2010 at 2:31
The reason why the new javadoc directory is not being checked out is because I
created it in parallel to the trunk directory, not inside it and you probably
have only checked out the trunk?
So at the moment, the software is here:
https://semanticvectors.googlecode.com/svn/trunk
and the javadoc for release version 1.30 is here
https://semanticvectors.googlecode.com/svn/javadoc/1.30
That is just a suggestion -- there are many ways how to solve this.
For example, if we want to keep the javadoc inside the software directory
(trunk) we could simply create a directory that is svn-managed which contains
the javadoc in subversion, but have the build tool create the file inside a
different, unmanaged directory.
I did not remove the current javadoc dir from inside the trunk yet, because I
thought I'll wait if everybody agrees with how to solve this.
Also, before we remove the doc from subversion, all the references to it in the
wiki must be updated.
Original comment by johann.petrak@gmail.com
on 28 Nov 2010 at 10:59
Ah one more thing: since we do have pointers to javadoc in various places, the
SVN URL for these files should not change over time, otherwise they have to be
updated at regular intervals.
So my proposal is to have a constant URL for the javadoc ... instead of naming
the tree e.g. "1.30" we could name it "latest-stable" for the latest release
version.
For the current development version in the trunk i would just call it "trunk".
So these questions remain:
* do we want to refer on the web page to the javadoc of the latest stable release or the current development trunk? If the latter, maybe we should build a distribution for that version too?
* do we want to have the *other* alternative online too? so even if we refer to the stable release in the wiki, do we still want the development release version of the javadoc available online too?
I guess this also depends on how often you want to make releases and how easy
it is to build a release distribution.
Original comment by johann.petrak@gmail.com
on 28 Nov 2010 at 11:06
Suggestions from me:
- I'd have online javadoc refer always to the latest stable release. Anyone
developing locally is generating fresh javadocs anyhow.
- So the release process should involve copying javadoc from he machine where
the distribution is built into the online svn directory and checking it in.
- In which case, could we redirect the build.xml file to generate javadocs in a
local directory, and then copy these to the existing doc directory when we do a
release? There's a bit of unnecessary svn churn then, but only with each
release, not with each commit.
Best wishes,
Dominic
Original comment by widd...@google.com
on 29 Nov 2010 at 2:10
I have removed the javadoc in the trunk and create ../javadoc/latest-stable
instead. Also changed a couple of wiki pages to refer to that new javadocs -
could be that I missed a couple of links in the wiki still.
For the release process, it is easiest to have the whole svn repository (not
just trunk) checked out or to have the javadoc dir checked out inside the same
parent directory as trunk. That way, the location of the javadoc for a released
version is always ../javadoc/latest-stable.
I guess the following steps would have to be carried out for a release:
* generate the javadoc in the trunk
* svn rm ../javadoc/latest-stable/*
* svn ci ../javadoc/latest-stable
* cp -r doc/* ../javadoc/latest-stable
* svn add ../javadoc/latest-stable/*
* set the svn:mime-type property on all .html files in the repository to
text/html
Or are there any ideas on how to simplify that?
Original comment by johann.petrak@gmail.com
on 3 Dec 2010 at 3:22
Fixing this as the main points are done. I'd suggest to add new issues if there
is something still broken and a separate issue for the automatic release build
process.
Original comment by johann.petrak@gmail.com
on 3 Dec 2010 at 3:24
Original issue reported on code.google.com by
johann.petrak@gmail.com
on 25 Nov 2010 at 10:49