Docs

Need to edit the docs?

The first thing you should do is check the documentation tree out from git.

$ git clone git://github.com/nimbusproject/nimbus.git

Local build (#)

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

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

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

The docs are currently going through a transition and one consequence is that this local serving tool does not present you with the style you see on the real website.


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. This kind of navigation "current" CSS class pattern is handled a lot better by other systems, this is a "bolt on" during the transition time.


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 git:
    $ cvs commit
  2. Log in to the computer where the live website lives:
    $ ssh USERNAME@login.mcs.anl.gov
  3. Make a scratch directory:
    $ mkdir /scratch/somedir && cd /scratch/somedir
  4. Get the documentation and scripts from git:
    $ git clone git://github.com/nimbusproject/nimbus.git
  5. $ cd nimbus/docs/scripts
  6. $ bash docscripts/push_to_mcs_web.sh X.Y

The "push_to_mcs_web.sh" will push any changes from the scratch directory to the live directory. The "X.Y" argument controls the target directory, e.g. "2.6" would push the current branch to the 2.6 subdirectory which is symlinked as the 'current' documentation at the time of this writing.

If you need to change something in an older release, you must switch into that branch (using "git checkout"), pull in the necessary changes and invoke that script with the appropriate version target.