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:

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

Step-by-step guide

  1. Create 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

  2. 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
 

  3. 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/
 

  4. 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

  5. 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

  6. 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'
  7. Refer to edgent-website developing page to local test and generate a pull request

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

 

 

  • No labels