PHENIX html documentation procedures


	Python-based Hierarchical ENvironment for Integrated Xtallography
Documentation Home

PHENIX html documentation procedures

Generating current PHENIX html documents
Creating and validating a new PHENIX html document

Generating current PHENIX html documents

This document is for PHENIX software developers who want to generate documentation for PHENIX modules. (For PHENIX users, all the documentation is predefined and you do not need read any further in this page.) First be sure that you have the latest contents of both $PHENIX/phenix/phenix/utilities and $PHENIX/phenix_html. To create the current PHENIX html, get into the directory $PHENIX and type:

./bin/build-html

This will generate some new raw files in $PHENIX/phenix_html/raw_files, read the list of files in html.list, use the raw xxx.htm_raw files in raw_files as templates and any python master_params specified in html.list to create a new set of .htm files in $PHENIX/phenix_html. NOTE: Do not edit the files in $PHENIX/phenix_html, only the files in $PHENIX/phenix_html/raw_files. Also those documents in $PHENIX/phenix_html/raw_files that are auto-generated (e.g. refinement.raw) should not be edited. The files in $PHENIX/phenix_html are overwritten every time you generate the current PHENIX html.

Creating and validating a new PHENIX html document

To create a new html document, you need to:

Copy any of the files in $PHENIX/phenix_html/raw_files to a new file name of your choice ($PHENIX/phenix_html/raw_files/mydoc.raw) with ending .raw. A good template to use is $PHENIX/phenix_html/raw_files/ligandfit.raw because it is not very large and it is easy to edit.
$PHENIX/phenix_html/raw_files/mydoc.raw will have just 2 sections you should edit. One is the title section which you can edit with your title and which is marked with:
```
Put your title here

<H4><U>Automated ligand fitting with LigandFit</U></H4>
```
The other is the body of the document where you can put any valid HTML that you want. This is indicated by:
```
<!--REMARK PHENIX BODY START   Put your text here.
Anything enclosed in header html H4 H5 etc will go in the table of contents>
```
There are several special rules however:
- Use the headings in the template files. The headings
```
<P><H5><U><B>Top Level</B></U></H5><P>
<P><H5><U>Top Level</U></H5><P>
```
  will be used as a top-level headers. The heading
```
<P><H5>Second Level</H5><P>
```
  will be used as a second-level header.
- All headings will be used in indexing your page. All the top-level and second-level headers (above) will be used to create a table of contents for your page.
Add a line to the file $PHENIX/phenix_html/html.list to specify your new $PHENIX/phenix_html/raw_files/mydoc.raw file and whether it is to be associated with any python file containing a master_params variable. Here is part of $PHENIX/phenix_html/html.list:
```
#.html file                     path                   python file w/o .py

tutorial_mad.htm                None                    None
refinement.htm                  phenix                  refinement
autobuild.htm                   phenix.command_line     autobuild
```
Add another line here with the name of the html file to be created in $PHENIX/phenix_html/ (substituting .htm for the .raw ending of your $PHENIX/phenix_html/raw_files/mydoc.raw file). The path is the path to a .py file for which you want to generate all the keywords. For example, autobuild.py is in the directory $PHENIX/phenix/phenix/command_line and is associated with the .raw file $PHENIX/phenix_html/raw_files/autobuild.raw, and the final document is in $PHENIX/phenix_html/autobuild.htm. The python file w/o .py is the name of that python file. This python file must have the variable master_params defining the parameters for this script.
Edit the PHENIX home page $PHENIX/phenix_html/phenix_documentation.html to create a link to your page if necessary.

Create a new version of the documentation with

phenix.python $PHENIX/phenix/phenix/utilities/toc_and_index.py

Look at your newly-created mydoc.htm that is in $PHENIX/phenix_html/mydoc.htm with firefox or another browser. Edit our mydoc.raw file and re-run the toc_and_index.py command as necessary.
Finally validate your newly-created mydoc.htm (i.e. the final, generated file) with the web service at validator.w3.org. When fixing problems, be sure to edit your mydoc.raw file and not the generated file! You should get rid of all errors.