
This directory contains scripts used to process and generate documentation for SimpleITK.

Overview:
Much of the SimpleITK documentation that is in the form of doxygen strings and
API language docs is derived from ITK's Doxygen. The process starts
when Doxygen is run on ITK and it produces the ITK Doxygen in XML
format. This can either be generated locally or the nightly can be
automatically downloaded. Next the JSONDocUpdate.sh script can be run
to extract the strings from the ITK XML Doxygen and update the
SimpleITK JSON filter descriptions. When SimpleITK is built the JSON
is used as source for the C++ code. Then when SimpleITK's Documentation
target is made, the SimpleITK Doxygen in XML will be generated. Lastly
the SwigDocUpdate.sh script can be run to convert the SimpleITK
Doxygen XML into Swig .i files so that when SimpleITK is built, inline
documenation for some wrapped languages will be available.

Building documentation with docker
        A docker configuration is available in the docker subdirectory.
	It contains a Dockerfile and run scripts to build the documentation.
        Results are saved in the docker folder. The process is executed from
        the docker folder using a command like:

        SIMPLEITK_GIT_TAG=v1.2.0 ./run.sh

        or to use another git repo:

        SIMPLEITK_GIT_TAG=MyTestBranch SIMPLEITK_GIT_REPO=https://github.com/username/SimpleITK.git ./run.sh

        Testing changes to the documentation scripts can use the docker framework as follows:
        1) Execute run.sh to create the appropriate container.
        2) Enter the docker via the bash entry point, with environment variables specifying the appropriate repo and branch:

        docker run -e _USER=$(id -un)  -e _USERID=$(id -u)  -e_GROUPID=$(id -g) \
        -e SIMPLEITK_GIT_TAG=v1.2.0  -e SIMPLEITK_GIT_REPO=https://github.com/username/SimpleITK.git \
        -v $(pwd):/work/io -ti --entrypoint /bin/bash  simpleitk_doxygen

        The bash entrypoint will place you in the /tmp directory. Run the documentation process using:

        /work/bin/cmd.sh

        This will check out SimpleITK and build the documents. You can change the documentation scripts for testing within the
        checked out copies.

Building the documentation target from the SuperBuild framework requires:
        The correct cmake flags: -DBUILD_DOXYGEN:BOOL=ON
        Run "make SimpleITK-doc" after a SuperBuild config, or "make Documentation"
	in the SimpleITK-build directory.
        This will create the SimpleITK-build/Documentation/xml content.

Important end use scripts (see script files for more details:
        JSONDocUpdate.sh - Copies ITK Doxygen into SimpleITK JSON
        SwigDocUpdate.sh - Copies SimpleITK Doxygen into Swig .i files and
                           R .Rd files.

        SwigDocUpdate requires python, with the regex library. regex is required for
	an evil recursive regular expression used to match bracket pairs of mbox in latex
	maths. R documentation doesn't implement all latex, and leaving the \mbox and \text
	fields causes problems when creating pdf versions of documentation in the package
	build process.

Configuration:
        The config_vars.sh file needs to be manually modified for the system and build configuration.

These scripts are manually run to modify and create files in the source tree with the derived documentation.
