diff --git a/README.md b/README.md index 33712673d2..709eca36f1 100644 --- a/README.md +++ b/README.md @@ -17,31 +17,70 @@ Overview This dockerfile has been created to facilitate the creation of [ITK](https://github.com/InsightSoftwareConsortium/ITK) -[Doxygen](https://doxygen.nl/) documentation in a reproducible way. +[Doxygen](https://doxygen.nl/) +documentation in a reproducible way. -The documentation is built nightly on the current/latest ITK commit, and -deployed to GitHub pages at: -https://insightsoftwareconsortium.github.io/ITKDoxygen/ +The documentation is built nightly on the current/latest ITK commit, +and deployed to GitHub pages at: https://insightsoftwareconsortium.github.io/ITKDoxygen/ -To create the the documentation locally, run the following commands: +To create the documentation locally, run the following commands: +### 1. Clone the ITKDoxygen Repository + +### 2. Build the Docker Image ```shell -docker build --build-arg TAG=v1.1.0 . -f Dockerfile -t itk-doxygen -docker build -f Dockerfile -t itk-doxygen . +docker build . -f Dockerfile -t itk-doxygen +``` -export TAG=v1.2.0 -docker run --env TAG --name itk-dox itk-doxygen +### 3. Export TAG Environment Variable +The `TAG` environment variable is used to specify a filename for the tarballs +to be copied from the Docker container to your local working directory (see +[step 5](#5-copy-the-doxygen-documentation)). +Useful for naming multiple versions of the documentation. + +Here we have set it to *alpha*, but you may change it as needed. +```shell +export TAG=alpha ``` -or +### 4. Run the Docker Container +#### Option 1: Using the Latest ITK Repository +```shell +docker run --env TAG --name itk-dox itk-doxygen +``` +#### Option 2: Using a Local ITK Repository +If you want to build documentation from a local ITK repository, +remove the `readonly` parameter from the mount command and +specify an absolute path to the aforementioned repository. ```shell docker run \ --env TAG \ - --mount type=bind,source=!ITK,destination=/work/ITK,readonly \ + --mount type=bind,source=/path/to/your/clone,destination=/work/ITK,readonly \ --name itk-dox itk-doxygen +``` +> **Note:** Both these commands may take a while to complete +### 5. Copy the Doxygen Documentation + +The following commands will copy the tarballs from the +Docker container to your local working directory. +```shell docker cp itk-dox:/ITKDoxygen.tar.gz SimpleITKDoxygen${TAG:+-${TAG}}.tar.gz docker cp itk-dox:/ITKDoxygenXML.tar.gz SimpleITKDoxygenXML${TAG:+-${TAG}}.tar.gz + +# Remove the Docker container after copying the tarballs docker rm itk-dox ``` + +### 6. Extract the Doxygen Documentation +Untar these tarballs to extract and verify the Doxygen documentation. +The `SimpleITKDoxygen` tarball contains the HTML documentation, +while the `SimpleITKDoxygenXML` tarball contains the XML documentation. + +```shell +tar -xzf SimpleITKDoxygen${TAG:+-${TAG}}.tar.gz +tar -xzf SimpleITKDoxygenXML${TAG:+-${TAG}}.tar.gz +``` + +You may now view the Doxygen documentation by opening the `html/index.html` file. \ No newline at end of file