numbas / editor-docs Goto Github PK

Documentation for the Numbas editor

License: Other

Makefile 14.64% CSS 18.38% HTML 29.08% Python 24.52% Batchfile 13.38%

documentation numbas sphinx

editor-docs's Introduction

Numbas is an open-source system for creating tests which run entirely in the browser. It has been developed by Newcastle University's School of Mathematics, Statistics and Physics.

For more information about Numbas and what it does, see our website at numbas.org.uk.

How to use Numbas

Documentation for Numbas users is at numbas-editor.readthedocs.org.

Installation

This repository contains the Numbas compiler, which runs as standalone Python 3, but the most convenient way to use Numbas is through the web-based editor.

A publicly-available editor, requiring no set-up, is available at numbas.mathcentre.ac.uk. Or, you can follow our instructions for Windows, Mac, or Ubuntu to install your own instance.

If you decide to run your own installation, install the compiler's dependencies with pip install -r requirements.txt.

This repository is just one part of the Numbas ecosystem. See the numbas organisation for the other pieces, including the web-based editor, extensions, and VLE integrations.

Contributing to Numbas

Numbas is open source, and we welcome contributions of any sort. Bug reports or feature suggestions can be added to the GitHub issue tracker, or emailed to [email protected].

See our page on contributing to Numbas for more information on how you can help.

We keep a list of tasks specifically for new contributors, under the good-first-issue label. There's a corresponding list in the editor repository, too. These tasks should be fairly straightforward to implement without much knowledge of how all the code fits together.

Development

This tool runs on the command line: run python bin/numbas.py to see the options. You can give it the name of a .exam file or pipe one in.

When making changes to the JavaScript runtime, it's a good idea to run the unit tests in the tests directory. These can run in a browser, or on the command-line.

Running tests in a browser

Start a local web server with python -m http.server and go to http://localhost:8000/tests. The tests under tests/jme contain tests to do with the JME system, and tests/parts contains tests to do with the part marking algorithms.

Running tests on the command-line

You can run the tests from the command-line using node.js:

Install the dependencies:

cd tests
npm install

Then run the tests with:

npm test

If you make a change, please try to add unit tests to confirm that Numbas behaves as expected.

The Makefile in this repository collects together scripts to run the unit tests, and builds the API documentation. Linux and Mac OS have built-in support Makefiles, but Windows doesn't. On Windows, cygwin provides make.

API documentation for developers is at numbas.github.io/Numbas. This is generated using JSDoc, with a custom template. Run make docs to rebuild the API documentation into ../numbas-docs.

Copyright

Copyright 2011-18 Newcastle University

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You can see a plain-English explanation of the license and what it allows at tl;drLegal

editor-docs's People

Contributors

Stargazers

Watchers

Forkers

xall chrismgraham calasworkshop georgestagg mousa15 shravanhp96 jessicaeb donutsteele

editor-docs's Issues

Minimum Web Browser Requirements

Is there any documentation available about the minimum web browser requirements for using Numbas (e.g. Internet Explorer versions 8 and above)?

Add instructions for the Numbas LTI tool to the "Uploading an exam to a VLE" page

No documentation for the implies logical operator

The inbuilt 'implies' logical operator in JME is not documented. This is a very common logical operator to use in logic questions, so it would be nice if it was in the documentation.

It looks like the information should be added to file editor-docs/source/jme-reference.rst where 'or','and' and 'xor' are mentioned.

Tutorials on different aspects of JME

The JME reference at the moment is a long list of functions. It's hard to get a feel for what's possible.

A few tutorials, maybe one per section in the reference, showing how to use the most important functions and common idioms, would help a lot.

"Assessed mode" and "practice mode" settings

Somewhere in the exam reference page, list the suggested settings for assessed mode and practice mode.

Is it worth including the code for the bookmarklet to switch modes?

Document running order of custom scripts

Recommended settings for Moodle SCORM module

Put this text somewhere in the Moodle instructions:

Set the default options for a SCORM package by going to Site administration -> Plugins -> Activity modules -> SCORM package.

Set Disable preview mode to Yes.
Set Display course structure in player to Disabled.
Set Hide navigation buttons to Yes.
Set Force new attempt to No.
Set Lock after final attempt to No.

No documentation on 'How to' add an svg image with variable text

I have seen a few nice questions that use scalable vector graphics with text that is updated as the question is generated. Unfortunately it is not as a simple as just using the 'insert image' in TinyMCE's interface (this will insert the image, but the referenced variables in the text won't update).

I have pieced together enough information to do this myself, but I think it would be nice to be have links to examples of this in the documentation. That way interested people can copy them and also figure out how they work.

Two nice examples of this are:

These demos are publicly available, but the questions are not. So it seems copies would need to be made to a place like the how to's project.

I was originally planning to write some documentation and submit a pull request, but I couldn't find "official" Numbas examples to link to (and my particular workflow for getting this working feels like a bit of a hack).

For example, in http://numbas-editor.readthedocs.org/en/latest/question-parts.html#choose-one-from-a-list-choose-several-from-a-list-match-choices-with-answers each of the subheadings (e.g. "Marking") is the same size as the glossary entries. It's very hard to read.

Remove console.log in Javascript function example

Write some documentation about how the default theme works

Layout of files
What each file does
Technologies involved (HTML, CSS, XSLT, jinja, XSLT, ...)