Warning: This document describes an old release. Check here for the current version.

Docs

Need to edit the docs?

WARNING: docs are in flux at the moment, this information is likely out of date.

The first thing you should do is check the documentation tree out from CVS. Because each past Nimbus version gets its own tree, the entire checkout is rather large. But you'll only need to do it once.


Checkout (#)

To check the docs out from CVS anonymously, run these commands:

$ export CVSROOT=:pserver:anonymous@cvs.globus.org:/home/globdev/CVS/globus-packages
$ cvs co -P -d nimbus-docs workspace/docs

To check the docs out from CVS with your own account (intending on committing changes directly and not via patch), run these commands with "USERNAME" replaced by your username:

$ export CVSROOT=:ext:USERNAME@cvs.globus.org:/home/globdev/CVS/globus-packages
$ cvs co -P -d nimbus-docs workspace/docs

Local build (#)

After you have a copy of the documentation tree, building and serving it locally takes one command:

$ sh nimbus-docs/scripts/build-and-serve-locally.sh

This will print the URL to navigate to in your browser (something like "http://localhost:8888")


Understanding macros (#)

The docs make heavy use of m4 which is a macro processor. The html page in the source tree will have something like _NIMBUS_HEADER in it which gets turned into the actual header HTML when the documentation is built.

The best bet is to start out by copying already created macros. If you want to create a new page, copy and paste the source contents (with the macros) of a page that will be next to it. Change the page title by altering the argument to the _NIMBUS_HEADER macro.

You will see something like "n,n,y,n,n,n,n" as an argument to some of the macros. This controls which option in a list is shaded/selected (like the main navigation bar or a subsection sidebar). To see which one to use, you may need to dip into the macro definitions in the "m4/worksp.lib.m4" file.


Popular macros (#)

To make a command appear like so:

$ sample command

... look for examples of the _EXAMPLE_GENERICCMD_BEGIN macro which must be closed off with the _EXAMPLE_CMD_END macro.

The _NAMELINK macro is useful for long pages, especially technical documentation. Whenever you make an anchor like so: <a name="some-section">

... put a _NAMELINK macro with an argument "some-section" like so: _NAMELINK(some-section)

See an example next to the subsections on this page, it produces a hidden link that will show up when you hover next to where the anchor takes you. This lets users and developers quickly find anchors so that specific sections of the documentation can be referred to over email etc.


Rebuilding after changes (#)

After you edit or add pages, preview the change by re-running the "build-and-serve-locally.sh" script. If it was already running, simply press CTRL-C and launch it again.

Once satisfied with the changes:

  1. Commit changes to CVS:
    $ cvs commit
  2. Log in to the computer where the live website lives:
    $ ssh USERNAME@cvs.globus.org
  3. Make a scratch directory:
    $ mkdir /sandbox/USERNAME/somedir && cd /sandbox/USERNAME/somedir
  4. Get the documentation scripts from CVS:
    $ export CVSROOT=:pserver:anonymous@cvs.globus.org:/home/globdev/CVS/globus-packages
  5. $ cvs co -d docscripts workspace/docs/scripts
  6. Check out and build the documentation:
    $ bash docscripts/push_to_mcs_web.sh

The "push_to_mcs_web.sh" will push any changes from the scratch directory to the live directory which lives @ "/www/workspace.globus.org/"

After running that all once, you can return anytime to that node/directory and run the following command to push any updates:

$ bash docscripts/push_to_mcs_web.sh update

Docs for new releases (#)

Making documentation for a new release consists of two different activities: 1) creating and customizing a new "vm/$VERSION" subtree for the new version and 2) updating everything else (like the changelog, download page, news, etc.).

  1. Copy the last release tree to the new release tree:
    $ cp -a vm/TP2.2 vm/TP2.3
  2. Remove any CVS directories:
    $ find vm/TP2.3 -name CVS -type d -print -exec rm -rf {} \;
  3. Find/replace any occurence of "2.3" in the tree with "2.4". Some of the occurences may be along the lines of "this feature is as of TP2.2" and it is not correct to change these.

  4. Make any inserts or changes that are necessary because of changes in the software from the previous version.

  5. Find/replace any occurrence of _NIMBUS_TP2_2_DEPRECATED in the TP2.3 tree with a new macro we will make called _NIMBUS_TP2_3_DEPRECATED

  6. Open the "m4/worksp.lib.m4" file and make _NIMBUS_TP2_2_DEPRECATED macro look like a previous one. And create a new _NIMBUS_TP2_3_DEPRECATED macro that has a comment only. This will make any page on the TP2.2 pages flash a big deprecated warning and provide a link to the most recent version. This is useful because people/search engines will often link to a page directly in a version's documentation: arriving here via such a link could mean the person will be unaware there is an update.

  7. Update the _WORKSP_PREVIOUS_VM_VERSION and _WORKSP_CURRENT_VM_VERSION macros in the same file.

  8. Update the "vm/changelog.html" page with all the new changes for the new release, give it a new section in the changelog that looks like the others.

  9. Update the "vm/faq.html" and "vm/features.html" pages with any relevant changes.

  10. Update the news with a release announcement (see a following section for information about how to do that).

  11. Once all of the tarballs are in place (see the release documentation), update "downloads/index.html" and "downloads/archive.html". Move the current links for the old release to the archive page and update all of the text and links on the "downloads/index.html" to reflect the new release.

  12. Add new files/directories to CVS and commit all the changes.

  13. Doublecheck what happened on the live site.


News items (#)

Making a news item requires editing three different files.

First, make a unique anchor <a> tag in "news.html" and create an entry that looks like the others. Only use full links to refer to the workspace documentation, do not use relative links. If you use full links then people can click on the links in their RSS readers and get to the site.

RSS is currently done manually. Open "rss.xml" and make a new section for a new item. Copy the title in for the title. Copy the anchor tag for the item into the fields to uniquely identify the item. Change the build date to reflect the current day. Now copy in the exact <p> tags and their contents into the RSS entry.

Copy the title and anchor into the front page of the website, "index.html" where the latest news entries are also mentioned. Delete the oldest item to make room.

Rebuild the documentation as discussed above. Test the RSS feed in your RSS reader but also use the link at the bottom of the "news.html" page to automatically test the validity of the rss.xml file against the RSS spec.