Skip to content

buildDocumentation.md

Latest commit

 

History

History
103 lines (59 loc) · 3.29 KB

buildDocumentation.md

File metadata and controls

103 lines (59 loc) · 3.29 KB

Building the Documentation (Windows)

The following sections describe how to build the CPACS schema documentation and tool-specific schema documentation on Windows using MSBuild.

Note
The instructions below describe the manual steps required to generate documentation from XSD files.
Alternatively, you may use the preconfigured batch scripts createDocumentation.bat and createToolspecificDocumentation.bat, which automate the process.

Ensure that both 7z and msbuild are available in your PATH environment variable, or adjust the scripts and commands to use explicit executable paths.

Build Documentation for cpacs_schema.xsd

Step 1: Extract Third-Party Dependencies

Extract the bundled third-party dependencies into the development directory (for example, using 7z):

7z x -y .\development\3rdparty.zip -odevelopment\

This command populates the external libraries required by the documentation build process.

Step 2: Install MSBuild (Visual Studio Build Tools)

The documentation build requires MSBuild, which is provided by either the Visual Studio Build Tools or a full Visual Studio installation (see Visual Studio Documentation for further details.). For example:

winget install -e --id Microsoft.VisualStudio.2022.BuildTools

After installation, open a new command prompt and verify that msbuild is available:

msbuild -version

Step 3: Install Microsoft HTML Help Compiler

The documentation build requires the Microsoft HTML Help Compiler (hhc.exe).

During installation, you may receive a warning indicating that a newer version than 1.3 is already installed. This warning can be safely ignored; the required components will still be installed and the build will succeed.

Step 4: Build the Documentation

Invoke MSBuild using the Release configuration:

msbuild /p:Configuration=Release documentation\Cpacs_doc_project.shfbproj

Build Tool-Specific Schema Documentation

Step 1: Prepare the Build Environment

Verify that all prerequisites have been completed:

  • Third-party dependencies extracted

  • MSBuild installed

  • Microsoft HTML Help Compiler installed

Step 2: Build the Tool-Specific Documentation

Run MSBuild for the tool-specific documentation project (example path shown below):

msbuild /p:Configuration=Release documentation\Toolspecific_doc_project.shfbproj

Adjust the MSBuild path as necessary to match your local Visual Studio installation.

Step 3: Adapt the Configuration File for Your Tool

Once the build completes successfully, the documentation build system is correctly configured.

To generate documentation for your own tool, adapt the project file:

documentation/Toolspecific_doc_project.shfbproj

Modify the configuration parameters as required to reference your tool-specific schema and metadata.