innoConv documentation

Table of contents

What is innoConv?

innoConv is a converter for educational content. It is used to turn content into a intermediate format that can be used with a content viewer.

Demo course

TODO

tub_base

Course structure

• toc.md
• language directories - chapters and sections in sub-directories - content.md

Viewers

At the moment there are two viewers in development.

innodoc-webapp

A React-based HTML5 web app. (Website)

innodoc-app

A React Native-based Smartphone App (Website)

Getting started

Prerequisites

innoConv is mainly used on Linux machines. It might work on Mac OS and Windows/Cygwin/WSL. You are invited to share experiences in doing so.

Dependencies

The only dependencies you have to provide yourself is Pandoc and the Python interpreter.

Python 3.7

While other versions of Python might work, innoConv was tested with Python 3.7. Make sure you have it available.

Pandoc

You need to make sure to have a recent version of the pandoc binary available in PATH (Pandoc 2.2.1 at the time of writing). There are several ways on installing Pandoc.

Installation

Using pip

TODO

In a virtual environment

It’s possible to install innoConv into a virtual environment. Setup and activate a virtual environment in a location of your choice.

$ python3 -m venv /path/to/venv
$ source /path/to/venv/bin/activate

Install innoConv in your virtual environment using pip.

$ pip install innoconv

If everything went fine you should now have access to the innoconv command.

The next time you login to your shell make sure to activate your virtual environment before using innoconv.

How to use innoconv

Run the converter in your content directory.

$ innoconv .

This will trigger the conversion for this content folder.

Command line arguments

usage: innoconv [-h] [-o OUTPUT_DIR] [-v] [-e EXTENSIONS] source_dir

Positional Arguments

source_dir

Content source directory

Named Arguments

-o, --output-dir
	Output directory (default: ./innoconv_output) Default: “./innoconv_output”
-v, --verbose	Print verbose messages (default: False) Default: False
-e, --extensions
	Enabled extensions (default: join_strings,copy_static,generate_toc,write_manifest) Default: “join_strings,copy_static,generate_toc,write_manifest”

Module overview

innoconv.constants

Project constants.

innoconv.constants.DEFAULT_OUTPUT_DIR_BASE

Default innoconv output directory

innoconv.constants.DEFAULT_EXTENSIONS

Default enabled extensions

innoconv.constants.ENCODING

Encoding used in this project

innoconv.constants.CONTENT_BASENAME

Basename for the content file in a section

innoconv.constants.MANIFEST_BASENAME

Manifest filename

innoconv.constants.STATIC_FOLDER

Static folder name

innoconv.runner

The innoConv runner is the core of the conversion process.

It traverses the source directory recursively and finds all content files. These are converted one-by-one to JSON. Under the hood is uses Pandoc.

It receives a list of extensions that are instantiated and notified upon certain events. The events are documented in AbstractExtension.

class innoconv.runner.InnoconvRunner(source_dir, output_dir, manifest, extensions)

Convert content files in a directory tree.

run()

Start the conversion by iterating over language folders.

innoconv.extensions

innoConv extensions.

Extensions are a way of extending the functionality of innoConv in a modular way. They can be enabled on a one-by-one basis.

innoconv.extensions.EXTENSIONS = {'copy_static': <class 'innoconv.extensions.copy_static.CopyStatic'>, 'generate_toc': <class 'innoconv.extensions.generate_toc.GenerateToc'>, 'join_strings': <class 'innoconv.extensions.join_strings.JoinStrings'>, 'write_manifest': <class 'innoconv.extensions.write_manifest.WriteManifest'>}

List of available extensions

innoconv.extensions.abstract

Base class for all other extensions.

The AbstractExtension is not meant to be instantiated directly.

class innoconv.extensions.abstract.AbstractExtension(manifest)

Abstract class for extensions.

The class all extensions inherit from. The to-be-implemented methods document the available events that are triggered during the conversion process.

Extension classes should have a _helptext attribute. It is shown in the CLI as a brief summary what the extension accomplishes.

classmethod helptext()

Return a brief summary of what the extension is doing.

start(output_dir, source_dir)

Conversion is about to start.

Parameters:

• output_dir (str) – Base output directory
• source_dir (str) – Content source directory

pre_conversion(language)

Conversion of a single language folder is about to start.

Parameters:language (str) – Language that is currently being converted.

pre_process_file(path)

Conversion of a single file is about to start.

Parameters:path (str) – Output path

post_process_file(ast, title)

Conversion of a single file finished. The AST can be modified.

Parameters:

• ast (List of content nodes) – File content as parsed by pandoc.
• title (str) – Section title (localized)

post_conversion(language)

Conversion of a single language folder finished.

Parameters:language (str) – Language that is currently being converted.

finish()

Conversion finished.

innoconv.extensions.copy_static

Extension that copies static files.

Content can include figures, images and videos. Static files can be included in a special folder named _static. The files will be copied to the output directory automatically.

Translation

It’s possible to have language-specific versions of a static file.

For that to work you need to have a _static folder beneath the language folder. Files in this folder will take precedence over the common _static folder for that language.

Example: en/_static/example.png takes precedence over _static/example.png in the English version.

Relative and absolute reference

Files can be referenced using relative or absolute paths.

Absolute paths are resolved to the root folder, either the common (_static) or language-specific (en/_static) folder.

Relative paths are resolved to the root folder but have the chapters path fragment appended.

Example

This example shows how a reference to an image is resolved. The references happen inside the section chapter01 in the English language version.

Type	Reference	Resolved to
Relative	subdir/my_picture.png	en/_static/chapter01/subdir/my_picture.png
Absolute	/subdir/my_picture.png (with leading /)	en/_static/subdir/my_picture.png

class innoconv.extensions.copy_static.CopyStatic(*args, **kwargs)

Bases: innoconv.extensions.abstract.AbstractExtension

Copy static files to the output folder.

This extension copies checks the AST for references to static files and copies them from the content source directory to the output directory.

start(output_dir, source_dir)

Remember directories.

pre_conversion(language)

Remember current conversion language.

pre_process_file(path)

Remember file path.

post_process_file(ast, _)

Generate list of files to copy.

finish()

Copy static files to the output folder.

innoconv.extensions.generate_toc

Extension that generates a table of contents.

A table of contents is generated from the course sections and added to the Manifest.

class innoconv.extensions.generate_toc.GenerateToc(*args, **kwargs)

Bases: innoconv.extensions.abstract.AbstractExtension

Generate a TOC from content sections.

start(output_dir, _)

Remember output directory.

pre_conversion(language)

Remember current conversion language.

pre_process_file(path)

Remember current path.

post_process_file(_, title)

Add this section file to the TOC.

innoconv.extensions.join_strings

Merge consecutive sequences of strings and spaces into a single string element.

The motivation behind this extension is to make the AST more readable and also to save space by compressing the representation. The actual appearance in a viewer should remain completely untouched.

This extension modifies the AST.

Example

Before	{"t": "Str", "c": "Foo"},{"t": "Space"},{"t": "Str", "c": "b!"}]
After	{"t": "Str", "c": "Foo b!"}]

class innoconv.extensions.join_strings.JoinStrings(*args, **kwargs)

Bases: innoconv.extensions.abstract.AbstractExtension

Merge consecutive strings and spaces in the AST.

post_process_file(ast, _)

Process AST in-place.

innoconv.extensions.write_manifest

Extension that writes a manifest.json to the output folder.

Every course needs a Manifest. Additionally to the fields from the source manifest it can include a table of contents and a glossary.

class innoconv.extensions.write_manifest.WriteManifest(*args, **kwargs)

Bases: innoconv.extensions.abstract.AbstractExtension

Write a manifest file when conversion is done.

start(output_dir, _)

Remember output directory.

finish()

Output course manifest.

innoconv.manifest

The manifest comprises course metadata.

A manifest.yml file needs to exist in every course content and resided at the content root directory. It is usually written by hand.

There is also a representation in the JSON format. It is generated automatically by the converter and additionally includes the table of contents that is generated from the section structure. It can be found in the output folder.

Example

title:
  en: Example title
  de: Beispiel-Titel
languages: en,de

class innoconv.manifest.Manifest(data)

Represents course metadata.

classmethod from_yaml(yaml_data)

Create a manifest from YAML data.

Parameters:yaml_data (str) – YAML representation of a manifest

class innoconv.manifest.ManifestEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

JSON encoder that can handle Manifest objects.

default(o)

Return dict for Manifest objects.

innoconv.utils

Utility module.

innoconv.utils.to_ast(filepath)

Convert a file to abstract syntax tree using pandoc.

Parameters:

filepath (str) – Path of file

Return type:

(list of dicts, str)

Returns:

(Pandoc AST, title)

Raises:

• RuntimeError – if pandoc exits with an error
• ValueError – if no title was found

Indices and tables

• Index
• Module Index
• Search Page