Commit ea2c7e23 authored by Pascal Sotin's avatar Pascal Sotin
Browse files

Rather clean initial version

parent d83dd930
M := Makefile
DOCDIR := doc
RSTT := python3 rstt2html.py
.PHONY: all
all: doc
.PHONY: doc
doc:
$(RSTT) $(DOCDIR)/doc-fr.rst > $(DOCDIR)/doc-fr.html
# Author: Pascal Sotin <pascal.sotin@univ-tlse2.fr>
"""
Activity directives (Connect, Observe, Produce).
"""
from docutils.nodes import Element, Inline
from docutils.parsers.rst import Directive
class ActivityInfo(Inline, Element):
def __init__(self,rawsource='', **kwargs):
Element.__init__(self, rawsource, **kwargs)
def visit(self, trans):
img = '<img src="rst/icons/' + self['label'] + '.png" \>'
overlay = '<a href="#" class="info" onclick="return false;">' + img + '<span>' + self['text'] + '</span></a>'
trans.body.append(overlay)
class Activity(Directive):
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
has_content = False
node_class = ActivityInfo
def run(self):
assert not self.has_content
text = self.arguments[0]
node = ActivityInfo(label=self.name, text=text)
return [node]
# Author: Pascal Sotin <pascal.sotin@univ-tlse2.fr>
"""
Improved hints.
"""
import base64
from docutils.nodes import Element
from docutils.parsers.rst import Directive
class HintInfo(Element):
javascript = """
<script type="text/javascript">
function ouvrirFermerHint(span)
{
var divContenu = span.parentNode.parentNode.getElementsByTagName('td')[1].getElementsByTagName('div')[0];
if(divContenu.style.display == 'block')
divContenu.style.display = 'none';
else
divContenu.style.display = 'block';
}
</script>
"""
written = False
def can_wrap(self):
return self['can_wrap']
def wrapped(self):
return self['wrapped']
def visit(self, trans):
if not HintInfo.written:
trans.head.append(HintInfo.javascript)
HintInfo.written = True
png = 'icons/hints/' + self['kind'].lower() + '.png'
base64png = base64.b64encode(open(png, 'rb').read()).decode()
if self.can_wrap():
show_hide = ' class="clickable" onclick="ouvrirFermerHint(this);"'
else:
show_hide = ''
if self.wrapped():
initial_display = 'none'
else:
initial_display = 'block'
opening = f'''<div class="admonitionblock"><table>
<tr><td class="icon">
<img alt="My Image" src="data:image/png;base64,{base64png}" {show_hide} />
</td><td class="content">'''
if self['title']:
opening += '<h4' + show_hide + '>' + self['title'] + '</h4>'
opening += '<div style="display: ' + initial_display +';">'
trans.body.append(opening)
def depart(self, trans):
closing = '</div></tr></table></div>'
trans.body.append(closing)
class Hint(Directive):
def valid_wrap(value):
accepted_values = ['no', 'maybe', 'yes']
if value is None or value in accepted_values:
return value
else:
raise ValueError('Expecting a value in ' + str(accepted_values))
required_arguments = 0
optional_arguments = 1
final_argument_whitespace = True
option_spec = {'wrap' : valid_wrap}
has_content = True
node_class = HintInfo
def run(self):
self.assert_has_content()
node = HintInfo(kind=self.name, title=self.title(),
can_wrap = self.can_wrap(), wrapped = self.wrapped_by_default())
self.state.nested_parse(self.content, self.content_offset, node)
return [node]
def title(self):
if self.arguments:
return self.arguments[0]
else:
return None
def wrap(self):
if 'wrap' in self.options:
return self.options.get('wrap')
else:
return None
def can_wrap(self):
if self.title() is None or self.wrap() == 'no':
return False
else:
return self.name in ['note', 'tip', 'lesson', 'help'] or self.wrap() in ['maybe', 'yes']
def wrapped_by_default(self):
if not self.can_wrap():
return False
elif self.wrap() == 'maybe':
return False
else:
return self.name == 'help' or self.wrap() == 'yes'
# Author: Pascal Sotin <pascal.sotin@univ-tlse2.fr>
"""
Solution directive.
"""
from docutils.nodes import Element
from docutils.parsers.rst import Directive
class SolutionInfo(Element):
def __init__(self, **kwargs):
Element.__init__(self, **kwargs)
def visit(self, trans):
opening = "<div class=\"section solution\">\n"
trans.body.append(opening)
def depart(self, trans):
closing = "</div>"
trans.body.append(closing)
class TeacherInfo(Element):
def __init__(self, **kwargs):
Element.__init__(self, **kwargs)
def visit(self, trans):
opening = "<div class=\"section teacher\">\n"
trans.body.append(opening)
def depart(self, trans):
closing = "</div>"
trans.body.append(closing)
class Solution(Directive):
active = False
required_arguments = 0
optional_arguments = 0
final_argument_whitespace = False
has_content = True
node_class = SolutionInfo
def run(self):
self.assert_has_content()
if Solution.active:
node = SolutionInfo()
self.state.nested_parse(self.content, self.content_offset, node)
return [node]
else:
return []
class Teacher(Directive):
active = False
required_arguments = 0
optional_arguments = 0
final_argument_whitespace = False
has_content = True
node_class = TeacherInfo
def run(self):
self.assert_has_content()
if Teacher.active:
node = TeacherInfo()
self.state.nested_parse(self.content, self.content_offset, node)
return [node]
else:
return []
Annotation des sujets
=====================
Signification des annotations
*****************************
.. note::
Une :code:`note` apporte des éléments culturels.
On peut tout à fait ne pas les lire.
.. tip::
Un :code:`tip` apporte des éléments techniques ou méthodologiques.
Il s'agit probablement de rappels.
Souvent placé après un travail à réaliser.
À lire avant d'appeler le prof.
.. lesson::
Une :code:`lesson` apporte des éléments théoriques ou techniques.
Il s'agit probablement de choses nouvelles qui mériteraient
d'être lues, retenues et qui seraient difficile à deviner.
Souvent placé avant un travail qui en dépend.
.. important::
Un :code:`important` annonce des éléments à prendre en considération
dans ce qui suit.
Doit éviter aux étudiants de se fourvoyer.
.. caution::
Un :code:`caution` demande aux étudiants de faire une pause avant de
continuer.
Signale un point que les étudiants risquent de prendre à la légère.
.. help::
Un :code:`help` contient des informations coup de pouce.
À priori les étudiants devraient ne pas en avoir besoin,
mais s'ils en ont besoin, c'est qu'il y a un couac dans
leur réflexion.
.. context::
Un :code:`context` apporte des informations sur le pourquoi
on fait ça, sur le où on en est.
.. goal::
Un :code:`goal` présente un objectif à atteindre.
Cette objectif doit motiver la réalisation de ce qui suit.
Titres et masquages
*******************
Une annotation peut avoir un titre.
.. note:: Pourquoi il ne faut pas habiller les animaux
- Parce que le cochon salirait ses vêtements
- Parce que la chèvre les mangerait
Une annotation peut être masquable ou non. Si elle est masquable, elle peut-être masquée par défaut ou non.
Pour être masquable, une annotation doit :
- Avoir un titre,
- Ne pas être marquée :code:`:wrap: no`
- Et soit :
- Être une :code:`note`, :code:`tip`, :code:`lesson`, :code:`help`
- Être marquée :code:`:wrap: maybe` ou :code:`:wrap: yes`
Pour être masquée par défaut, une annotation doit :
- Être masquable,
- Et soit :
- Être une :code:`help`,
- Être marquée :code:`:wrap: yes`
Quiz (en développement)
************************
.. note::
En français, *quiz* s'écrit avec un seul *z* au singulier comme au pluriel.
En anglais, c'est *quiz* au singulier et *quizzes* au pluriel.
Proposer des quiz dans un sujet permet de le rythmer et de s'assurer qu'une notion est connue, ou apprise sur le tas, avant de poursuivre.
Code couleur :
+----------------+-----------------+-----------------------+
| Bleu-gris | Rouge | Vert (foncé / clair ) |
+----------------+-----------------+-----------------------+
| À réaliser | Réponse erronée | Réponse correcte |
| | | (du 1e coup / corrigé)|
+----------------+-----------------+-----------------------+
#!/usr/bin/python3
"""
A minimal front end to the Docutils Publisher, producing HTML.
Inspired by rst2html.py (2006-05-21).
"""
from translator import Writer
import sys
try:
import locale
locale.setlocale(locale.LC_ALL, '')
except:
pass
from docutils.core import publish_cmdline, default_description
description = ('Generates HTML documents from reStructuredText extended to produce teaching supports.'
+ default_description)
def extract_boolean_option(name):
try:
sys.argv.remove(name)
return True
except ValueError:
return False
solution = extract_boolean_option('--solution')
teacher = extract_boolean_option('--teacher')
writer = Writer(teacher=teacher, solution=solution or teacher)
publish_cmdline(writer=writer, description=description)
from docutils.writers import html4css1
from docutils.parsers.rst import directives
from directives.activity import Activity
from directives.solution import Solution, Teacher
from directives.hint import Hint
class MyHTMLTranslator(html4css1.HTMLTranslator):
def visit_SpoilerInfo(self, node):
node.visit(self)
def depart_SpoilerInfo(self, node):
node.depart(self)
def visit_ActivityInfo(self, node):
node.visit(self)
def depart_ActivityInfo(self, node):
pass
def visit_TeacherInfo(self, node):
node.visit(self)
def depart_TeacherInfo(self, node):
node.depart(self)
def visit_SolutionInfo(self, node):
node.visit(self)
def depart_SolutionInfo(self, node):
node.depart(self)
def visit_HintInfo(self, node):
node.visit(self)
def depart_HintInfo(self, node):
node.depart(self)
def visit_admonition(self, node):
kind = node[0][0]
png = 'rst/icons/hints/' + kind.lower() + '.png'
del node[0]
self.body.append('<div class="admonitionblock"><table><tr><td class="icon"><img src="'
+ png + '"</td><td class="content">')
html4css1.HTMLTranslator.visit_admonition(self, node)
def depart_admonition(self, node):
html4css1.HTMLTranslator.depart_admonition(self, node)
self.body.append('</tr></table></div>')
class Writer(html4css1.Writer):
def __init__(self, teacher=False, solution=False):
Teacher.active = teacher
Solution.active = solution
directives.register_directive("dico", Activity)
directives.register_directive("connect", Activity)
directives.register_directive("observe", Activity)
directives.register_directive("produce", Activity)
directives.register_directive("teacher", Teacher)
directives.register_directive("solution", Solution)
directives.register_directive("caution", Hint)
directives.register_directive("context", Hint)
directives.register_directive("help", Hint)
directives.register_directive("lesson", Hint)
directives.register_directive("important", Hint)
directives.register_directive("note", Hint)
directives.register_directive("tip", Hint)
directives.register_directive("goal", Hint)
html4css1.Writer.__init__(self)
self.translator_class = MyHTMLTranslator
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment