Skip to content

Latest commit

 

History

History
111 lines (72 loc) · 2.67 KB

BUILDING.rst

File metadata and controls

111 lines (72 loc) · 2.67 KB
Raw

The GNU "make" program and Python are used to build the NeXus documentation. The default build assembles the HTML version. You have the choice to build the documentation in two places:

  • in the source tree
  • out of the source tree

In-Tree documentation

To build the NeXus documentation within the source tree, go to the root directory (the directory where this README file is located), and type:

make clean
make

The HTML documentation is located in this folder:

./manual/build/html/

Out-of-Tree documentation

There are two ways to build out-of-source.

Outside the source tree

To build the NeXus documentation outside the source tree,

  1. create the target directory for the documentation to be built:

    mkdir /some/where/else

  2. note the definitions source directory (the directory where this README file is located):

    export SOURCE_DIR=/path/to/nexus/definitions

  3. copy the source to the target using this NeXus Python tool:

    cd /some/where/else
python $(SOURCE_DIR)/utils/build_preparation.py $(SOURCE_DIR)

  4. build the documentation:

    make clean
make

The HTML documentation is located in this folder:

/some/where/else/manual/build/html/

Inside the source tree, in a temporary directory

Alternatively, as is a common practice with cmake, you can build out-of-source (sort of) in a temporary $(SOURCE_DIR)/build directory. For this, the Makefile has the builddir rule:

export SOURCE_DIR=/path/to/nexus/definitions
cd $(SOURCE_DIR)
make builddir
cd build
make clean
make

This is all done with one make command:

export SOURCE_DIR=/path/to/nexus/definitions
cd $(SOURCE_DIR)
make makebuilddir

The HTML documentation is located in this folder:

$(SOURCE_DIR)/build/manual/build/html/

Windows

Windows development needs more instructions. Use the cmd.exe shell to build the documentation, not the Windows powershell or there will be Python problems.

Python errors

On Windows, if the following error is output to the console after typing make html in the $(SOURCE_DIR)/manual directory:

'python' is not recognized as an internal or external command, operable program or batch file.

it may be necessary to add Python to the PATH environment variable, such as one of these lines:

set PATH=C:\Python27;%PATH%
set PATH=D:\Apps\Anaconda;%PATH%

Try to avoid installing Python on a directory path that has embedded spaces. Long series of tedious problems with that.