From e4b6a6952838b86301433c706c6f5bf111a84b35 Mon Sep 17 00:00:00 2001 From: bonartm Date: Sat, 6 Mar 2021 15:32:02 +0100 Subject: [PATCH] add readme and license --- LICENSE | 25 +++++++++++++++++++++ README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..094167b --- /dev/null +++ b/LICENSE @@ -0,0 +1,25 @@ +Copyright (c) 2021 by Malte Bonart +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..9d059a3 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ + # sphinxcontrib-quizdown + +Sphinx extension for [`quizdown.js`](https://github.com/bonartm/quizdown-js). Write quizzes directly in your content or +include external `.md` files. + +## Installation + +First, install the library with: + +```bash +pip install git+git://github.com/bonartm/sphinxcontrib-quizdown +``` + +Then change the `conf.py` of your Sphinx project: + +```python +extensions = [ + ..., + 'sphinxcontrib.quizdown'. + ... +] +``` + +## Usage + +A new directive is added that let's you write markdown-like quizdown inside your `.rst` documents: + +```rst +.. quizdown:: + + ## What is the capital of Germany? + + > It's the largest city in Germany. + + - [x] Berlin + - [ ] Cologne + - [ ] Frankfurt + - [ ] Munich +``` + +You can also write you quiz in an external markdown file and reference it like so: + +```rst +.. quizdown:: quiz.md +``` + +The HTML builder will wrap a `
` around the text and +includes the `quizdown.js` library in the build. + +To use another version of quizdown or change the syntax highlighting you can set +the following options in your project's `conf.py`: + +```python +# quizdown javascript +quizdown_js='https://cdn.jsdelivr.net/gh/bonartm/quizdown-js@latest/public/build/quizdown.js' +# quizdown css +quizdown_css='https://cdn.jsdelivr.net/gh/bonartm/quizdown-js@latest/public/build/quizdown.css' +# stylesheet for syntax highlighting +quizdown_highlight_css='https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.6.0/build/styles/github.min.css' +``` + + +## Acknowledge + +[sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid) and the [sphinx-contrib template](https://github.com/sphinx-contrib/cookiecutter) served as a reference for this project. Thank you for the inspiration! \ No newline at end of file