Dashboard > Admin > Home > 04 Project Procedures > Documentation Generation and Deploy
Admin
Documentation Generation and Deploy
Added by Jody Garnett , last edited by Administrator on Mar 18, 2013  (view change)
Labels: 
(None)

Documentation is now stored in github as Rich Structured Text files and compiled into the net.refractions.udig.help plugin.

Generate Documentation

The docs/pom.xml file always has the latest instructions.

  1. The docs module will use sphinx (if installed) to compile the RST files into HTML.
    cd docs
    mvn clean install
    
  2. The doc module also has a test case to detect any missing pages between toc.xml and the RST files.
    The test failure will list any missing pages and provide an XML fragment you can use to update toc.xml.

Help Plugin

  1. To refresh the net.refractions.udig.help/EN folder:
    cd docs
    ant help-clean
    ant help-deploy
    
  2. Stage the docs in net.refractions.udig.help
    cd ..
    git add plugins/net.refractions.udig.help
    git add 
    git status
    
  3. You may need to use "git rm" to clean away any old file references
  4. And then commit and push up the new docs:
    git commit -m "Update online help docs"
    git push
    

Publish to udig.github.com

Set up the following:

  1. Use git to checkout the udig.github.com repository:
    git clone git@github.com:uDig/udig.github.com.git udig.github.com
    
  2. Going to assume you have the following directory structure:
    udig-platform/ <-- udig platform checkout you are working on
    udig.github.com/ <-- clone of udig.github.com created above
    

Deploy User Guide

Deploy generated sphinx docs to udig.github.com:

  1. Build development and user docs as described in the docs pom.xml modules
    cd udig-platform
    cd docs
    mvn clean install
    
  2. Switch over to the website and pull down any changes to avoid conflict
    cd ../..
    cd udig.github.com/docs
    git pull
    
  3. Remove the whole content from udig.github.com/docs/user folder and
    copy generated docs into udig.github.com/docs/user/
    rm -rf user
    cp -R ../../udig-platform/docs/target/user/en/html/ user
    
  4. Stage the changes for the remote repository
    git add user
    git status
    
  5. You may have to use git rm to clean up after any removed files
  6. Commit the changes and push to publish:
    git commit -m "refresh user guide"
    git push
    

Deploy Developers Guide

  1. You can perform the same steps to publish the developers guide:
    (makes sense if anybody deleted pages from docs or renamed images).
    rm -rf dev
    cp -R ../../udig-platform/docs/target/devel/en/html/ dev
    
  2. Stage these changes for the remote repository
    git add dev
    git status
    
  3. You may need to use "git rm" to clean away any old file references
  4. You can then commit and push the changes to deploy
    git commit -m "refresh developer guide"
    git push
    
  5. Done! (github will depoly the content and after a few minutes the new docs are online)

Powered by a free Atlassian Confluence Open Source Project License granted to uDig. Evaluate Confluence today.
Powered by Atlassian Confluence 2.7.1, the Enterprise Wiki. Bug/feature request - Atlassian news - Contact administrators
User-friendly Desktop Internet GIS