corda/docs/source/building-the-docs.rst

Building the documentation

The documentation is under the docs folder, and is written in reStructuredText format. Documentation in HTML format is pre-generated, as well as code documentation, and this can be done automatically via a provided script.

Building Using the Docker Image

This is the method used during the build. If you run:

./gradlew makeDocs

This will download a docker image from docker hub and run the build locally inside that by mounting quite a bit of the docs directory at various places inside the image.

This image is pre-built with the dependencies that were in requirements.txt at the time of the docker build.

Changing requirements

If you want to upgrade, say, the version of sphinx that we're using, you must:

• Upgrade the version number in requirements.txt
• Build a new docker image: cd docs && docker build -t corda/docs-builder:latest -f docs_builder/Dockerfile .
  • post doing this the build will run using your image locally
  • you can also push this to the docker registry if you have the corda keys
  • you can run docker run -it corda/docs-builder /bin/bash to interactively look in the build docker image (e.g. to see what is in the requirements.txt file)

Building from the Command Line (non-docker)

Requirements

In order to build the documentation you will need a development environment set up as described under building-corda.

You will also need additional dependencies based on your O/S which are detailed below.

Windows

Git, bash and make

In order to build the documentation for Corda you need a bash emulator with make installed and accessible from the command prompt. Git for Windows ships with a version of MinGW that contains a bash emulator, to which you can download and add a Windows port of make, instructions for which are provided below. Alternatively you can install a full version of MinGW from here.

1. Go to ezwinports and click the download for make-4.2.1-without-guile-w32-bin.zip
2. Navigate to the Git installation directory (by default C:\Program Files\Git), open mingw64
3. Unzip the downloaded file into this directory, but do NOT overwrite/replace any existing files
4. Add the Git bin directory to your system PATH environment variable (by default C:\Program Files\Git\bin)
5. Open a new command prompt and run bash to test that you can access the Git bash emulator
6. Type make to make sure it has been installed successfully (you should get an error like make: *** No targets specified and no makefile found. Stop.)

Python, Pip and VirtualEnv

1. Visit https://www.python.org/downloads
2. Scroll down to the most recent v2 release (tested with v.2.7.15) and click the download link
3. Download the "Windows x86-64 MSI installer"
4. Run the installation, making a note of the Python installation directory (defaults to c:\Python27)
5. Add the Python installation directory (e.g. c:\Python27) to your system PATH environment variable
6. Add the Python scripts sub-directory (e.g. c:\Python27\scripts) to your system PATH environment variable
7. Open a new command prompt and check you can run Python by running python --version
8. Check you can run pip by running pip --version
9. Install virtualenv by running pip install virtualenv from the commandline
10. Check you can run virualenv by running virtualenv --version from the commandline.

LaTeX

Corda requires LaTeX to be available for building the documentation. The instructions below are for installing TeX Live but other distributions are available.

1. Visit https://tug.org/texlive/
2. Click download
3. Download and run install-tl-windows.exe
4. Keep the default options (simple installation is fine)
5. Open a new command prompt and check you can run pdflatex by running pdflatex --version

Debian/Ubuntu Linux

These instructions were tested on Ubuntu Server 18.04 LTS. This distribution includes git and python so only the following steps are required:

Pip/VirtualEnv

1. Run sudo apt-get install python-pip
2. Run pip install virtualenv
3. Run pip --version to verify that pip is installed correctly
4. Run virtualenv --version to verify that virtualenv is installed correctly

LaTeX

Corda requires LaTeX to be available for building the documentation. The instructions below are for installing TeX Live but other distributions are available.

1. Run sudo apt-get install texlive-full

Build

Once the requirements are installed, you can automatically build the HTML format user documentation, PDF, and the API documentation by running the following script:

// On Windows
gradlew buildDocs

// On Mac and Linux
./gradlew buildDocs

Alternatively you can build non-HTML formats from the docs folder.

However, running make from the command line requires further dependencies to be installed. When building in Gradle they are installed in a python virtualenv, so they will need explicitly installing by running:

pip install -r requirements.txt

Change directory to the docs folder and then run the following to see a list of all available formats:

make

For example to produce the documentation in HTML format run:

make html