Metadata-Version: 2.0
Name: ybe
Version: 0.2.2
Summary: Simple software package for storing exams.
Home-page: https://github.com/robbert-harms/ybe
Author: Robbert Harms
Author-email: robbert@xkls.nl
Maintainer: Robbert Harms
Maintainer-email: robbert@xkls.nl
License: GPL v3
Keywords: exams-management-system,yaml,markdown,QTI,exams,IMS Question & Test Interoperability,quiz,test,exam,assessment,LaTeX,plain-text
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Scientific/Engineering
Requires-Dist: ruamel.yaml
Requires-Dist: lxml
Requires-Dist: pypandoc
Requires-Dist: jinja2
Requires-Dist: beautifulsoup4

######################
YBE - Yaml Based Exams
######################
Ybe is a software package supporting a `YAML <https://en.wikipedia.org/wiki/YAML>`_ based file format for importing,
exporting and storing exams in a plain text file. It supports multiple-choice, multiple-response and essay questions.
Due to the extensive meta-data storage, storing exams in ybe allows you to easily search, annotate and recombine questions into new exams.
Exams can be written as a LaTeX file, or be exported to the QTI format and be imported by Canvas and other educational software.

********
Examples
********
Questions can be stored in a plain text file using `YAML <https://en.wikipedia.org/wiki/YAML>`_ for structure and
`Markdown <https://en.wikipedia.org/wiki/Markdown>`_ for the content of the questions.


Minimal .ybe file
=================

For example, a minimal example of a multiple choice question is given by:

.. code-block:: yaml

    ybe_version: 0.2.0

    questions:
    - multiple_choice:
        id: q1
        points: 1
        text: Example multiple choice question.
        answers:
            - answer:
                text: First answer
            - answer:
                text: Second answer
                correct: true


This defines a list of questions with only one question. The ``id`` is meant to be provide
a unique identifier to every question and should be unique for every question in an .ybe file.
The points define the worth of the question.
The text is in Markdown format and allows all Markdown operators.
The answers are again a list with Markdown text blocks and a marked correct answer.


Exporting to QTI
================
If you would copy the previous Ybe content into a text file named ``example.ybe``, you could export it to a QTI using:

.. code-block:: python

    from ybe import read_ybe_file
    from ybe.lib.qti_writer import \
        write_qti_zip, \
        ConvertCanvasEquations

    ybe_exam = read_ybe_file('example.ybe')

    # QTI with Canvas style equations
    write_qti_zip(ybe_exam, 'qti_canvas.zip',
                  text_formatter=ConvertCanvasEquations())



Exporting to LaTeX
==================
Alternatively, you could output your exam to a Latex file read for printing:

.. code-block:: python

    from ybe import read_ybe_file, write_latex_file

    ybe_exam = read_ybe_file('example.ybe')
    write_latex_file(ybe_exam, 'main.tex')


Supported question types
========================
An example of an ybe file with all supported questions and some file meta data is given by:

.. code-block:: yaml

    ybe_version: 0.2.0

    info:
        title: Example questions
        description: Example of all questions.
        document_version: 0.1.0
        date: 2020-05-24
        authors:
            - The Author

    questions:
    - multiple_choice:
        id: q1
        points: 1
        text: Example multiple choice question.
        answers:
            - answer:
                text: First answer
            - answer:
                text: Second answer
                correct: true

    - open:
        id: q2
        points: 3
        text: Example open question.

    - multiple_response:
        id: q3
        points: 2
        text: A multiple response question is a
            multiple choice question, where
            multiple answers are possible.
        answers:
            - answer:
                text: First answer
                correct: true
            - answer:
                text: Second answer
            - answer:
                text: Third answer
                correct: true
            - answer:
                text: Fourth answer

    - text_only:
        id: q4
        text: |-
            Since "text" is short for "text_markdown",
            you can use Markdown syntax to markup
            your document.

            For example:

            1. this is a list
            2. *with this in italics*
            3. **and in bold**

            This is a famous formula inline: $E=mc^2$
            and this is a basic displayed formula:

            $$ a^2 = b^2 + c^2 $$


Adding meta-data
================
In addition, Ybe supports adding meta-data to your questions.
A full example of all the available meta-data options is given below.
Not all the options need to be used, one can leave one or more out if not needed.
A full example:

.. code-block:: yaml

    questions:
    - open:
        id: q5
        points: 1
        text: Example with meta data
        meta_data:
            general:
                description: Some description
                keywords: [alpha, beta]
                language: en
                creation_date: 2020-05-29
                authors:
                    - John Doe
                module: Science
                chapters:
                    - Some book, ed. 2, ch. 1
                    - Some book, ed. 3, ch. 2
                skill_type: Knowledge
                difficulty: 1
            analytics:
                - exam:
                    name: 2020_qz1
                    participants: 1
                    nmr_correct: 0
                - exam:
                    name: 2020_qz1
                    participants: 200
                    nmr_correct: 25


Searching your questions
========================
If you would save the above in a file ``example.ybe``, you could then search through the questions easily.
For example, finding all questions that yield exactly one point can be done like:

.. code-block:: python

    from ybe import read_ybe_file

    ybe_exam = read_ybe_file('example.ybe')

    for question in ybe_exam.questions:
        if question.points == 1:
            print(question)



Importing from QTI
==================
If you already have questions in `Canvas <https://canvas.instructure.com>`_ or other software packages, you could export
these to QTI format and convert easily into an .ybe file:

.. code-block:: python

    from ybe import read_qti_zip, write_ybe_file
    from ybe.lib.utils import copy_ybe_resources

    ybe_exam = read_qti_zip('qti_file.zip')

    # write the ybe file
    write_ybe_file(ybe_exam, './qti_to_ybe.ybe')

    # and write the images referred to in the QTI
    copy_ybe_resources(ybe_exam, './')



*******
Summary
*******
In general:

* Storing exams in a plain-text ``.ybe`` file
* Importing and exporting to and from QTI
* Write exams to LaTeX
* API for scripting exams

Technical details:

* Free software: GPL v3 license
* Full documentation: https://ybe.readthedocs.io
* Project home: https://github.com/robbert-harms/ybe


************************
Quick installation guide
************************
Ybe requires Python 3.8+. Either use your package manager, or install a Python distribution like `Anaconda <https://www.anaconda.com/distribution/>`_.
After that it is typically as simple as:

.. code-block:: bash

    pip install ybe


**Linux**

For Ubuntu 18.xx you need to install Python 3.8 first, for example see here: https://linuxize.com/post/how-to-install-python-3-8-on-ubuntu-18-04/.
Afterwards, simply install using:

.. code-block:: bash

    pip3 install ybe

For other Linux distributions the setup is typically similar, install Python 3.8 and then install ybe.

**Windows**

* Install Anaconda Python 3.8
* Open an Anaconda shell and type: ``pip install ybe``


**Mac**

* Install Anaconda Python 3.8
* Open an Anaconda shell and type: ``pip install ybe``


