From a81fbadec5bcb34873b0c03c87cc499d030cdec6 Mon Sep 17 00:00:00 2001 From: Ben Wyeth Date: Wed, 27 Mar 2019 15:40:36 +0000 Subject: [PATCH] CORDA-2808 docs build page (#4947) * updated the docs build docs to be a bit more up to date with the docker image being used * fixing the indented bullets --- docs/source/building-the-docs.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/source/building-the-docs.rst b/docs/source/building-the-docs.rst index 2bf1b5dcdd..85673f6c3a 100644 --- a/docs/source/building-the-docs.rst +++ b/docs/source/building-the-docs.rst @@ -4,6 +4,36 @@ 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: + +.. code-block:: shell + + ./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 ------------