search

dileepajayakody / semanticvectors

Automatically exported from code.google.com/p/semanticvectors
Other
1 stars 0 forks source link

The JavaDoc documents should not be checked into the repository #32

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
I think it would be better not to have the JavaDocs checked into the repository 
because a local build will modify them all and make them show up modified with 
respect to the repository.

Original issue reported on code.google.com by johann.petrak@gmail.com on 25 Nov 2010 at 10:49

GoogleCodeExporter commented 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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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