{"id":1975,"date":"2018-04-05T17:13:39","date_gmt":"2018-04-05T16:13:39","guid":{"rendered":"https:\/\/www.andyjohnson.uk\/?p=1975"},"modified":"2018-04-05T17:13:39","modified_gmt":"2018-04-05T16:13:39","slug":"notes-on-generating-printable-keras-documentation","status":"publish","type":"post","link":"https:\/\/andyjohnson.uk\/blog\/2018\/04\/05\/notes-on-generating-printable-keras-documentation\/","title":{"rendered":"Notes on generating printable Keras documentation"},"content":{"rendered":"

It started when I wanted to print the documentation for Keras<\/a> so that I could peruse it on a train journey. Obviously this is a weird thing to want to do in at least two different ways, but sometimes you’ve just got to have ink on paper.<\/p>\n

The online HTML documentation for Keras is built from extended markdown<\/a> files, and can (in theory – hence this post) also be used to generate a PDF file. However, when I tried it there turned out to be a few “issues”, so I thought I’d document this in case anyone (including future-me) wants to go on the same journey. I’m not going to document the process of discovery I went though, just what seems to be the easiest route to getting a printable PDF. Note that these instructions are for Windows.<\/p>\n

Ready? Lets go.<\/p>\n

Part 1: Install the prerequisites.<\/h2>\n

1. Install Python 3.6<\/a> if you don’t already have it.<\/p>\n

2. Download and install mkdocs<\/a>. I used pip3 to do this. It will install itself into <user>\\AppData\\Local\\Pandoc and you’ll need to add this to your path.<\/p>\n

3. Download and install\u00a0mkdocs-pandoc<\/a>.<\/p>\n

4. Download and install MiKTeX<\/a>. mkdocs-pandoc emits LaTeX and expects you to have a way to convert this to PDFusing pdflatex.exe<\/span>, which is included in MiKTeX (and probably other TeX distributions). Choosing the option to automatically install missing packages will save time later. Add\u00a0C:\\Program Files\\MiKTeX 2.9\\miktex\\bin\\x64<\/span> to your path.<\/p>\n

5. Download the Keras repo<\/a> from Github and unzip keras-master.zip<\/span>. You’ll need this because it includes the documentation source files.<\/p>\n

Part 2: Generate the PDF<\/h2>\n

1. In an command window, go to keras-master\/docs<\/span>. You’ll see a readme.md<\/span> file containing instructions for building the docs. We’ll be following this outline but adding some workarounds.<\/p>\n

2. Run\u00a0python autogen.py<\/span> and wait for errors to occur:<\/p>\n

\n

Traceback (most recent call last):<\/span>
\nFile “autogen.py”, line 559, in <module> readme = read_file(‘..\/README.md’) File “autogen.py”, line 532, in read_file return f.read() File “C:\\Program Files\\Python36\\lib\\encodings\\cp1252.py”, line 23, in decode return codecs.charmap_decode(input,self.errors,decoding_table)[0] UnicodeDecodeError: ‘charmap’ codec can’t decode byte 0x81 in position 7411: character maps to <undefined><\/span><\/p>\n<\/blockquote>\n

This is happening because autogen.py<\/span> is trying to read files that don’t match the default file encoding. We’ll need to hack autogen.py<\/span>, so open it in an editor ando to the first place that f.read()<\/span> is called, which for me was line 532. Change the previous<\/em> line from<\/p>\n

with open(path) as f:<\/span><\/p><\/blockquote>\n

to<\/p>\n

with open(path, encoding=”latin1″<\/strong>) as f:<\/span><\/p><\/blockquote>\n

Save autogen.py<\/span> and run the command again. You should get a similar error on a different line (it was line 563 for me) so fix it the same way. Save autogen.py<\/span> and run the command yet again. This time it should complete successfully and generate a bunch of markdown files in the sources<\/span> directory.<\/p>\n

3. Run the mkdocs serve<\/span> command. This does some stuff and starts a local web server. Since this blocks the command window, you’ll need to start another command window and go to the docs<\/span> directory.<\/p>\n

4. In the new command window, run\u00a0mkdocs build<\/span>. This generates an html web site in the site<\/span> directory. This may not be strictly necessary, but its a useful check that things are working.<\/p>\n

5. At this point we leave the instructions in readme.md<\/span> behind. Run the command mkdocs2pandoc > keras.pd<\/span>. This creates a single large markdown file (keras.pd<\/span>) that is optimised for generating PDFs.<\/p>\n

6. The markdown document has a few problems at this point, which we can rectify by hand-editing it. I used notepad++<\/a> for this.<\/p>\n