updating java index,Updating Javadocs

It is very important to provide the appropriate Javadoc for Edgent users. Javadoc is also included in the Source, but it must also be accessible via the Webpage.

This page explains how to update the Javadoc to the latest version, and how to add the Javadoc when a new release is created.

These steps are specific for the release process described in Release Manager Guide.  For other scenarios and for more information see incubator-edgent/DEVELOPMENT.md.

Preparations

Javadoc is in the incubator-edgent-website repository, but the source code for creating it is in the incubator-edgent repository.

Prepare:Refer to edgent-website contributing page and fork/clone the incubator-edgent-website repository.

Step-by-step guideCreate a new clone of the tagged Edgent release. This presumes the release process's 'release:prepare' step has been performed.

#Clone the tagged release

git clone --branch edgent-1.2.0 https://git-wip-us.apache.org/repos/asf/incubator-edgent.git javadoc-edgent-1.2.0

#Move to clone's root directory

cd javadoc-edgent-1.2.0

Create Javadoc via maven. It will be created in the path under javadoc-edgent-1.2.0/target/site/apidocs/

#Edit the maven-javadoc-plugin configuration in the top pom.xml

# uncomment the "aggregate" reportSet config

# DO NOT COMMIT THE CHANGE TO GIT

vi pom.xml

#Run maven wrapper(For Windows, run mvnw.bat)

./mvnw install -DskipTests

./mvnw site

#After the build is complete, make sure the Javadoc is created

# Open target/site/apidocs/index.html in your browser

# Verify it shows the expected Edgent version

# Verify it has the expected aggregated/categorized format

# Optionally navigate a bit to check to further check it

Go to the incubator-edgent-website clone directory, create a branch for the website changes and copy / overwrite the generated Javadoc to the appropriate location. The location of the Javadoc is under incubator-edgent-website/site/javadoc/

#Go to the website javadoc directory

cd ../incubator-edgent-website/site/javadoc/

#Work on an up to date master branch

git checkout master

git pull upstream

#Create a new branch

git checkout -b edgent???-updateFor-r1.2.0

#When creating the specific version of Javadoc

mkdir r1.2.0

cp -r ../../../javadoc-edgent-1.2.0/target/site/apidocs/ r1.2.0/

#When creating the latest Javadoc

rm -rf latest

mkdir latest

cp -r ../../../javadoc-edgent-1.2.0/target/site/apidocs/ latest/

It does not matter if it is latest, but if you add a new version of Javadoc, add the new version information and location to top-nav

#Open the topnav.yml file and append information in javadoc_dropdowns section.

vi incubator-edgent-website/site/_data/mydoc/mydoc_topnav.yml

Review the status of your website repository and stage modified and new pages (e.g., from new classes and/or samples) and/or a new javadoc version directory

#Review changes from step 3 and 4

git status

...

Changes not staged for commit:

...

modified: site/_data/mydoc/mydoc_topnav.yml# from step 4

modified: latest/allclasses-frame.html# from step 3

modified: latest/...

...

Untracked files:

../../_site# IGNORE, DO NOT ADD

latest/org/...# from step 3

r1.2.0# from step 3

# if applicable, stage the changes to mydoc_topnav.yml

git add site/_data/mydoc/mydoc_topnav.yml

# if applicable, stage the changes to latest (modified, new)

git add latest

# if applicable, stage the new javadoc version directory

git add r1.2.0

Commit the changes to your branch

#Check status again and keep iterating on step 5 until your workspace has the correct set of committed changes

git status

...

#Commit the staged changes

git commit -m 'EDGENT[???] update website javadoc for release X.Y.Z'

Refer to edgent-website developing page to local test and generate a pull request

You can remove the temporary javadoc-edgent-X.Y.Z clone that you created