python3 converter.py
usage: converter.py [-h] [--generate GENERATE] [-l LOG] [-y] [-r] PATH [PATH ...]

Usage

Generic toc generation

By passing path to tex file and folder for output files generic structure will be generated

All actions means that ThinkJava2 book is placed in ThinkJava2 directory

Example: python3 converter.py --generate ThinkJava2/thinkjava.tex example

Generated config will be placed to example folder

R markdown convert

see subdocumentation

Config options

workspace

• directory base directory of book
• tex book name
• removeTrinket remove trinket entries
• removeExercise remove exercise headers
• useCodeFolder put source code files to code directory

Examples

workspace:
  directory: ThinkJava2
  tex: thinkjava.tex

assets

relative paths for assets, globing supports

Examples

assets:
  - code
  - figs: "*.png"

metadata

Global guides settings

Examples

metadata:
  hideMenu: false
  protectLayout: false

Available options:

1. scripts - array of JS-script
2. lexikonTopic - string
3. suppressPageNumbering - true|false - Do not show section numbers
4. useSubmitButtons - true|false - Use Submit buttons
5. useMarkAsComplete - true|false - Show mark as complete
6. hideMenu - true|false - Hide top menu
7. allowGuideClose - true|false - Allow Guide to be closable
8. collapsedOnStart - true|false - Collapsed on start
9. hideSectionsToggle - true|false - Hide sections toggle
10. hideBackToDashboard - true|false - Hide "Back to dashboard" button
11. protectLayout - true|false - Prevent tabs closing by students

sections

Pages rules

Examples

sections:
  - name: Preface
    type: chapter

sections.configuration

The page configuration

Examples

    configuration:
      layout: 2-panels
      files:
        - path: "code/ch03/GuessSoln.java"
          panel: 0
          action: open

Available options:

1. layout - string, guides layout, see Supported layouts
2. learningObjectives - string, learning objectives
3. teacherOnly - true|false - show only to teacher
4. path - array of string, open folder nodes in tree
5. files - array of file info objects, see File info objects

Supported layouts

1. 1-panel-tree - 1 Panel with tree
2. 1-panel - 1 Panel without tree
3. 2-panels-tree - 2 Panels with tree
4. 2-panels - 2 Panels without tree
5. 2-panels-guides-left - 2 Panels without tree (Guides Left)
6. 3-columns-tree - 3 Columns with tree
7. 3-columns - 3 Columns without tree
8. 3-cell-tree - 3 Panels with tree
9. 3-cell - Panels without tree
10. 3-cell-left - 3 Panels without tree (Guides Left)
11. 4-cell-tree - 4 Panels with tree
12. 4-cell - 4 Panels without tree

File info objects

1. close all tabs (as first item in array)

        - path: "#tabs"
          action: close

2. open file, panel - panel number

        - path: "code/ch03/GuessSoln.java"
          panel: 0
          action: open

3. open preview, panel - panel number

        - path: "#preview: https://codio.com/docs"
          panel: 0
          action: open

3. execute terminal, panel - panel number

        - path: "#terminal: echo \"hello\""
          panel: 0
          action: open

3. python tutor visualizer, panel - panel number

        - path: "#tutor: code/example.java"
          panel: 0
          action: open

3. point code line in a file, panel - panel number, ref line content

        - path: "test.html"
          panel: 0
          action: open
          ref: "line2"
          lineCount: 1

sections.transformations

transformation could be an string skip - remove item from procession or described below dicts

    transformations: skip

The page transformations Supports 2 transformations:

• add

    transformations:
      - add: My simple text
        position: 79
      - add: |
          this is my very very very
          long string
          with multilines
        position: 244

• remove

    transformations:
      - remove: 5
        position: 74

Content not existed in book

It is possible to add own content via insert_sections

You should specify chapter and section which exists in book for identify a place for insert

    chapter: Computer programming
    section: What is programming?

insert_sections:
  - name: Exercises 1.1
    type: section
    chapter: Computer programming
    section: What is programming?
    before: false
    latex: |
      hello latex
  - name: Exercises 1.2
    type: section
    chapter: Computer programming
    section: What is programming?
    before: false
    markdown: |
      hello markdown

Refs

Show available refs in book python3 converter.py example -r

You could override ref counting of \ref instruction by directive(changees in chapter counting)

refs:
  chapter_counter_from: 0

Also you could override any \ref or \pageref output by override rules

refs:
  overrides:
    JUnit:
      pageref: Testing with JUnit
      ref: '16.7'
    UML:
      pageref: 100
      ref: '11.7'

If you are using a string for pageref in generated md file prefix in section will be added If a number - no additional

Сode syntax highlighting

Sets syntax highlighting in all code blocks in accordance with the programming language specified via code_syntax

code_syntax: java

Book generation

As we placed config to example directory, a book content could be generated by command

python3 converter.py example

Generated content will be placed to example/generate folder

PDF to JPG

A book author used an PDFs as graphics in lot of places, so generation from pdf to jpg was added as markdown do not support PDFs preview

First you need poppler-utils

pdftoppm and pdftocairo are the piece of software that do the actual magic. It is distributed as part of a greater package called poppler.

Windows users will have to install poppler for Windows, then add the bin/ folder to PATH.

Mac users will have to install poppler for Mac.

Linux users will have both tools pre-installed with Ubuntu 16.04+ and Archlinux. If it's not, run sudo apt install poppler-utils

Required a package pip3 install pdf2image

Image optimization

If you want to resize all images or optimize them add following directives

optimization:
  imageWidth: 660
  imageHeight: 400
  optimizeImages: true

• imageWidth image max width, resize with aspect ration
• imageHeight image max height, resize with aspect ration

optimizeImages - run program for optimizations, requires jpegoptim and optipng to be installed

• Mac OS X: brew install OptiPNG and brew install jpegoptim
• Ubuntu: sudo apt-get install optipng and sudo apt-get install jpegoptim

codestyle

tests

Unit

python3 -m unittest discover -s tests/unit -v

Functional

python3 -m unittest discover -s tests/functional -v