corda/docs/docs_builder/lexer-fix/readme.md

Pygments lexer

We were getting a lot of warnings in the docs build, and people were unable to see the real warnings due to this. So we're on a mission to sort all of these out.

A lot of the errors were because the kotlin lexer in Pygments (the syntax highlighter that sphinx uses) didn't cope with a lot of the kotlin syntax that we use.

We have fixes for the kotlin lexer that we are trying to get checked into Pygments, but while this is taking place we need to maintain a slightly hacked corda/docs-build docker image in which to build the docs.

Some notes on building and testing

The sphinx/pygments brigade have delightfully decided that mercurial is a good idea. So broadly speaking, to build/test a fix:

• checkout pygments from here

• copy the two python files in (might be worth diffing - they're based on 2.3.1 - nb the kotlin test is entirely new)

• build pygments whl file

  cd /path/to/pygments/
  python setup.py install
  pip install wheel
  wheel convert dist/Pygments-2.3.1.dev20190  # obviously use your version
  cp Pygments-2.3.1.dev20190401-py27-none-any.whl /path/to/corda/docs/source/docs_builder/lexer-fix
  

• build the latest docker build (see docs readme)

  cd docs
  docker build -t corda/docs-builder:latest -f docs_builder/lexer-fix/Dockerfile .
  

• push the new image up to docker hub (nb you can also test by going to /opt/docs and running ./make-docsite.sh)