README-docs

The pyast html docs are hosted on github project pages
(https://help.github.com/articles/creating-project-pages-manually/)
associated with the main pyast repo. The main page is published at

http://starlink.github.io/starlink-pyast/pyast.html

The associated files are stored on the "gh-pages" branch of the main
repository.

The files pyast.html, node1.html and node2.html are generated by running
script "make_doc" and should not therefore be changed manually. The
make_doc script needs to be told the paths to a local copy of sun211.tex
(the C docs) and Ast.c (the main python wrapper file). make_doc copies
the contents of "dochead.html" and "doctail.html" to the beginning and
end of pyast.html. So any changes made to "dochead.html or doctail.html
will appear in pyast.html.

The other html files are static and can be changed manually.

make_doc should be run whenever:

- New functions are added to sun/211
- New wrappers are added to Ast.c
- API for existing wrappers in Ast.c are changed
- dochead.html or doctail.html are changed.

% make_doc <path/to/sun211.tex>  <path/to/Ast.c>

A typical scenario is:

% cd starlink-pyast

<add a new wrapper to Ast.c or make some other change>
% git commit -a -m "Added wrapper for astFred"

% cp starlink/ast/Ast.c ./
% git checkout gh-pages
% make_doc
% git commit -a -m "Added wrapper for astFred"
% git push origin gh-pages
% git checkout master