Coursebuilder produces flexible and accessible course notes, in a variety of formats, from LaTeX or Markdown source. It is aimed primarily at notes in the mathematical sciences.

This repository, makecourse, is a python package providing the command line interface for building notes with CourseBuilder.

A set of course notes are provided in either Markdown or LaTeX along with a configuration file config.yml. The makecourse command then builds the requested outputs based on the contents of the configuration file.

• Markdown parsing is provided by Python Markdown.
• LaTeX parsing is provided by plasTeX.

• Ensure a system TeX distribution such as TeX Live or MacTeX is installed.
• Install pdf2svg using your standard package manager (e.g. apt install pdf2svg)
• Install libyaml using your standard package manager (e.g. apt install libyaml-dev)
• Ensure the virtualenv python package is installed.

• Create a Python3 virtualenv: virtualenv -p python3 coursebuilder_env and activate it: source ./coursebuilder_env/bin/activate
• Install makeCourse: pip install git+https://github.com/coursebuilder-ncl/makecourse.git

The command makecourse is now available for use. You should now compile the sample course and ensure everything works.

• Create a Python3 virtualenv: virtualenv -p python3 coursebuilder_env and activate it: source ./coursebuilder_env/bin/activate
• Clone the repository: git clone https://github.com/coursebuilder-ncl/makecourse.git
• cd makecourse
• Install all the requirements: pip install -r requirements.txt
• Install the makecourse tool into your environment: pip install -e .

The command makecourse is now available for use. You should now compile the sample course and ensure everything works.

• Install the makecourse package using the instructions above
• Clone the sample course: git clone https://github.com/coursebuilder-ncl/sample_course.git
• Change into the directory you just cloned to and run make local to build and view a local version of the sample course.
• The finished website output will be in ./sample_course/build

LaTeX is compiled using the plasTeX python package. While it supports a large array of TeX and LaTeX features, not all packages are compatible. Complex packages must be implemented in python independently.

If your notes are not compiling at all, the first thing to do is to take a look at which LaTeX packages you are using. Try removing one or more, simplifying your notes, until things start working. Complex packages that use PDF special commands are a common problem.

If your notes compile, but the output is broken, you should check indiviual mathematical equations in your notes. Coursebuilder renders mathematics on the web with MathJax, and not all features available in LaTeX work in MathJax out of the box.

In short you should start with short, simple LaTeX documents and slowly build up complexity once they are converting through CourseBuilder cleanly!

Reinstall pyyaml, ensuring that it is linked to the system libyaml by issuing the command: pip --no-cache-dir install --verbose --force-reinstall -I pyyaml