This project is for building a public-facing page describing the Technology Integration Group, NCCS, ORNL.

The master copy resides at

https://github.com/ORNL-TechInt/ORNL-TechInt-Page

Here's an outline of the recipe for making a change:

• Get a copy of the repo (see "Gitting a Copy")

• Edit the files and review your changes (see "Making Changes", "Special Measures", and "Implications")

• Deploy the updated files (see "Deploying Changes")

$ git clone git@github.com:ORNL-TechInt/ORNL-TechInt-Page.git [dirname]

$ git clone git://github.com/ORNL-TechInt/ORNL-TechInt-Page.git [dirname]

Edit the .src files (see "Special Measures" and "Implications"below). Running mkhtml will generate .html from the .src files. Git will keep track of your updates. You can see the results of your changes by running

$ make review

and visiting http://users.nccs.gov/~UID/techint/ in your browser (where UID is your NCCS username). 'make review' deploys the site in your account at $HOME/www/techint.

NOTE: Running 'make review' will only work on a machine where /ccs/wwwusers is mounted. Examples are home, dtnXX, rhea, etc.

$ git commit -a  (you'll be asked to write something describing your update)
$ git push
$ make deploy

This sequence will 1) commit your changes to your local git repo, 2) push your changes up to the shared repository at github.com, and 3) deploy the files to /ccs/wwwproj/stf008/techint where they'll be visible through the URL http://techint.nccs.gov.

%include('hdrnav.inc')

%ifeq(self.filetype, 'index')
      <li class="current_page" />
       <a class="current_page" href="index.html">About</a>
%else
      <li/>
       <a href="index.html">About</a>
%endif

<meta name="keywords" content="index" />

• To change HTML content, edit the corresponding .src file. If you're just updating the git repository so someone else can fetch it and deploy your change, that's all you need to do (well, except for 'git commit -a' and 'git push'). The person redeploying the files must run make after the .src files are up to date to rebuild the .html files.

• The .css file will be reloaded by browsing requests directly (the user may need to issue a refresh), so there's no need to rebuild after changing the .css.

• To add a new member to the group, a new thrust area, or a new year to the publications or software categories, several files must be updated. Let's take a new group member as an example. Here are the steps:

  • Create a new .src file based on the person's name. The convention so far has been to use last names unless that results in a collision, in which case we add the first initial (eg., cwang.src and fwang.src for Chao and Feiyi).

  • Add the new file to the ALL_MEMBERS list in Makefile.

  • Add a new <li> tag for the new entry in hdrnav.inc.

  • Add a new <li> tag for the new entry in members.src.

  • Run 'make review' to examine the changes in your personal web area (http://users.nccs.gov/~UID/techint/index.html)

  • Once satisfied with your updates, commit and push the changes in the master branch.

  • Run 'make deploy' to update the production website at http://techint.nccs.gov. NOTE: This must be done on a machine with /ccs/wwwproj mounted.

• For a new year in publications or software, add the new material to publications.src or software.src and a new <li> tag in hdrnav.inc. After that, review and verify the changes, then commit and push. Finally, run 'make deploy'.

The following targets are available in the Makefile:

• all: rebuild all html files from .src and .inc files. This is the default target that gets run if make is invoked with no arguments.

• %.html: tells make that foo.html depends on foo.src as well as all the .inc files

• review: deploys the site to $HOME/www/techint. After running this, you should be able to view the result in your browser by visiting http://users.nccs.gov/~UID/techint/ (where UID is your lowercase username). Use this to verify that your changes had the effect you intended.

• deploy: deploys the site to /ccs/wwwproj/stf008/techint, which is where the URL techint.nccs.gov points.

• README.html: run Markdown.pl to generate README.html

• mkhtml: creates symlink mkhtml -> mkhtml.py if needed

• clean: removes generated files

• w3valid: runs each .html file through validator.w3.org. If there are errors in foo.html, they are saved in validation_foo.html.

• valid: run the local python validation checks on the .html files.

• validate: create symlink validate -> validate.py if needed

• version: generate the javascript version file based on 'git describe'

• With some work, I think we could get rid of mkhtml and replace it with jekyll (or some other static file generator).