Add renderer for Sphinx .rst files, for user manual previews #2
28
sphinx/README.md
Normal file
28
sphinx/README.md
Normal file
@ -0,0 +1,28 @@
|
||||
# Sphinx RST to HTML Preview
|
||||
|
||||
Command for generating previews of RST files on projects.blender.org.
|
||||
|
||||
The template is adapted from the Blender manual to support the same extensions.
|
||||
|
||||
### Deployment
|
||||
|
||||
Install dependencies.
|
||||
|
||||
pip3 install -r requirements.txt
|
||||
|
||||
Add to Gitea app.ini.
|
||||
|
||||
[markup.restructuredtext]
|
||||
ENABLED = true
|
||||
FILE_EXTENSIONS = .rst
|
||||
RENDER_COMMAND = "timeout 30s ./custom/sphinx/sphinx_to_html.py --user sphinx --user-work-dir /path/to/dir"
|
||||
IS_INPUT_FILE = true
|
||||
|
||||
[repository.editor]
|
||||
LINE_WRAP_EXTENSIONS = .txt,.md,.markdown,.mdown,.mkd,.rst
|
||||
PREVIEWABLE_FILE_MODES = markdown,restructuredtext
|
||||
|
||||
The `sphinx` user is required for sandboxing of sphinx-build which we do not
|
||||
assume to be secure. The work directory should be writable by both the gitea
|
||||
user and sphinx user, with the sphinx user having as little access as possible
|
||||
to other directories.
|
1
sphinx/requirements.txt
Normal file
1
sphinx/requirements.txt
Normal file
@ -0,0 +1 @@
|
||||
sphinx==6.1.3
|
110
sphinx/sphinx_to_html.py
Executable file
110
sphinx/sphinx_to_html.py
Executable file
@ -0,0 +1,110 @@
|
||||
#!/usr/bin/python3
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import os
|
||||
import pathlib
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
|
||||
parser = argparse.ArgumentParser(prog="sphinx_to_html")
|
||||
parser.add_argument("filename_rst", help="Input .rst file")
|
||||
parser.add_argument("--user", help="Run sphinx as another user", type=str)
|
||||
parser.add_argument("--user-work-dir", help="Do work in specified folder accessible by user", type=str)
|
||||
args = parser.parse_args()
|
||||
|
||||
base_url = "https://projects.blender.org"
|
||||
local_url = "http://localhost:3000"
|
||||
placeholder_url = "https://placeholder.org"
|
||||
|
||||
# Gitea sets this environment variable with the URL prefix for the current file.
|
||||
gitea_prefix = os.environ.get("GITEA_PREFIX_SRC", "")
|
||||
if gitea_prefix.startswith(base_url):
|
||||
gitea_prefix = gitea_prefix[len(base_url):]
|
||||
if gitea_prefix.startswith(local_url):
|
||||
gitea_prefix = gitea_prefix[len(local_url):]
|
||||
|
||||
if len(gitea_prefix):
|
||||
org, repo, view, ref, branch = gitea_prefix.strip('/').split('/')[:5]
|
||||
|
||||
doc_url = f"{base_url}/{org}/{repo}/{view}/{ref}/{branch}"
|
||||
image_url = f"{base_url}/{org}/{repo}/raw/{ref}/{branch}"
|
||||
else:
|
||||
doc_url = ""
|
||||
image_url = ""
|
||||
|
||||
# Set up temporary directory with sphinx configuration.
|
||||
with tempfile.TemporaryDirectory(dir=args.user_work_dir) as tmp_dir:
|
||||
work_dir = pathlib.Path(tmp_dir) / "work"
|
||||
|
||||
script_dir = pathlib.Path(__file__).parent.resolve()
|
||||
shutil.copytree(script_dir / "template", work_dir)
|
||||
page_filepath = work_dir / "contents.rst"
|
||||
shutil.copyfile(args.filename_rst, page_filepath)
|
||||
|
||||
page_contents = page_filepath.read_text()
|
||||
|
||||
# Turn links into external links since internal links are not found and stripped.
|
||||
def doc_link(matchobj):
|
||||
return f"`{matchobj.group(1)}<{doc_url}/{matchobj.group(2).strip('/')}.rst>`_"
|
||||
def ref_link(matchobj):
|
||||
return f"`{matchobj.group(1)} <{placeholder_url}>`_"
|
||||
def term_link(matchobj):
|
||||
return f"`{matchobj.group(1)} <{placeholder_url}>`_"
|
||||
def figure_link(matchobj):
|
||||
return f"figure:: {image_url}/{matchobj.group(1).strip('/')}"
|
||||
def image_link(matchobj):
|
||||
return f"image:: {image_url}/{matchobj.group(1).strip('/')}"
|
||||
|
||||
page_contents = re.sub(":doc:`(.*)<(.+)>`", doc_link, page_contents)
|
||||
page_contents = re.sub(":ref:`(.+)<(.+)>`", ref_link, page_contents)
|
||||
page_contents = re.sub(":ref:`(.+)`", ref_link, page_contents)
|
||||
page_contents = re.sub(":term:`(.+)`", term_link, page_contents)
|
||||
page_contents = re.sub("figure:: (.+)", figure_link, page_contents)
|
||||
page_contents = re.sub("image:: (.+)", image_link, page_contents)
|
||||
|
||||
# Disable include directives and raw for security. They are already disabled
|
||||
# by docutils.py, this is just to be extra careful.
|
||||
def include_directive(matchobj):
|
||||
return f"warning:: include directives disabled: {html.escape(matchobj.group(1))}"
|
||||
def raw_directive(matchobj):
|
||||
return f"warning:: raw disabled: {html.escape(matchobj.group(1))}"
|
||||
page_contents = re.sub("literalinclude::.*", include_directive, page_contents)
|
||||
page_contents = re.sub("include::(.*)", include_directive, page_contents)
|
||||
page_contents = re.sub("raw::(.*)", raw_directive, page_contents)
|
||||
|
||||
page_filepath.write_text(page_contents)
|
||||
|
||||
# Debug processed RST
|
||||
# print(html.escape(page_contents).replace('\n', '<br/>\n'))
|
||||
# sys.exit(0)
|
||||
|
||||
# Run sphinx-build.
|
||||
out_dir = work_dir / "out"
|
||||
out_filepath = out_dir / "contents.html"
|
||||
|
||||
sphinx_cmd = ["sphinx-build", "-b", "html", work_dir, out_dir]
|
||||
if args.user:
|
||||
result = subprocess.run(sphinx_cmd, capture_output=True, user=args.user)
|
||||
else:
|
||||
result = subprocess.run(sphinx_cmd, capture_output=True)
|
||||
|
||||
# Output errors.
|
||||
error = result.stderr.decode("utf-8", "ignore").strip()
|
||||
if len(error):
|
||||
error = error.replace(str(page_filepath) + ":", "")
|
||||
error = html.escape(error)
|
||||
print("<h2>Sphinx Warnings</h2>\n")
|
||||
print(f"<pre>{error}</pre>")
|
||||
print("<p>Note the preview is not accurate and warnings may not indicate real issues.</p>")
|
||||
|
||||
# Output contents of body.
|
||||
if result.returncode == 0 and out_filepath.is_file():
|
||||
contents = out_filepath.read_text()
|
||||
body = contents.split("<body>")[1].split("</body>")[0]
|
||||
body = body.replace(placeholder_url, "#")
|
||||
body = body.replace('href="http', 'target="_blank" href="http')
|
||||
print(body)
|
22
sphinx/template/conf.py
Normal file
22
sphinx/template/conf.py
Normal file
@ -0,0 +1,22 @@
|
||||
# Configuration file for RST preview.
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
# Extensions
|
||||
sys.path.append(os.path.abspath('exts'))
|
||||
extensions = [
|
||||
'reference',
|
||||
'peertube',
|
||||
'sphinx.ext.mathjax',
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.todo',
|
||||
]
|
||||
|
||||
# Project
|
||||
project = 'projects.blender.org'
|
||||
root_doc = 'contents'
|
||||
|
||||
# Theme: epub hides all navigation, sidebars, footers.
|
||||
html_theme = 'epub'
|
||||
html_permalinks = False
|
6
sphinx/template/docutils.conf
Normal file
6
sphinx/template/docutils.conf
Normal file
@ -0,0 +1,6 @@
|
||||
# Disable file inclusion and raw HTML for security.
|
||||
# https://docutils.sourceforge.io/docs/howto/security.html
|
||||
[parsers]
|
||||
[restructuredtext parser]
|
||||
file-insertion-enabled:false
|
||||
raw-enabled:false
|
160
sphinx/template/exts/peertube.py
Executable file
160
sphinx/template/exts/peertube.py
Executable file
@ -0,0 +1,160 @@
|
||||
#!/usr/bin/env python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
import re
|
||||
from docutils import nodes
|
||||
from docutils.parsers.rst import directives, Directive
|
||||
from sphinx.environment import BuildEnvironment
|
||||
from sphinx.locale import __
|
||||
from sphinx.util import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def get_size(d, key):
|
||||
if key not in d:
|
||||
return None
|
||||
m = re.match(r"(\d+)(|%|px)$", d[key])
|
||||
if not m:
|
||||
raise ValueError("invalid size %r" % d[key])
|
||||
return int(m.group(1)), m.group(2) or "px"
|
||||
|
||||
|
||||
def css(d):
|
||||
return "; ".join(sorted("%s: %s" % kv for kv in d.items()))
|
||||
|
||||
|
||||
class peertube(nodes.General, nodes.Element):
|
||||
pass
|
||||
|
||||
|
||||
def visit_peertube_node(self, node):
|
||||
instance = node["instance"]
|
||||
aspect = node["aspect"]
|
||||
width = node["width"]
|
||||
height = node["height"]
|
||||
|
||||
if not (self.config.peertube_instance or instance):
|
||||
logger.warning(__("No peertube instance defined"))
|
||||
return
|
||||
|
||||
if instance is None:
|
||||
instance = self.config.peertube_instance
|
||||
|
||||
if aspect is None:
|
||||
aspect = 16, 9
|
||||
|
||||
div_style = {}
|
||||
if (height is None) and (width is not None) and (width[1] == "%"):
|
||||
div_style = {
|
||||
"padding-bottom": "%f%%" % (width[0] * aspect[1] / aspect[0]),
|
||||
"width": "%d%s" % width,
|
||||
"position": "relative",
|
||||
}
|
||||
style = {
|
||||
"position": "absolute",
|
||||
"top": "0",
|
||||
"left": "0",
|
||||
"width": "100%",
|
||||
"height": "100%",
|
||||
}
|
||||
attrs = {
|
||||
"src": instance + "videos/embed/%s" % node["id"],
|
||||
"style": css(style),
|
||||
}
|
||||
else:
|
||||
if width is None:
|
||||
if height is None:
|
||||
width = 560, "px"
|
||||
else:
|
||||
width = height[0] * aspect[0] / aspect[1], "px"
|
||||
if height is None:
|
||||
height = width[0] * aspect[1] / aspect[0], "px"
|
||||
style = {
|
||||
"width": "%d%s" % width,
|
||||
"height": "%d%s" % (height[0], height[1]),
|
||||
}
|
||||
attrs = {
|
||||
"src": instance + "videos/embed/%s" % node["id"],
|
||||
"style": css(style),
|
||||
}
|
||||
attrs["allowfullscreen"] = "true"
|
||||
div_attrs = {
|
||||
"CLASS": "peertube_wrapper",
|
||||
"style": css(div_style),
|
||||
}
|
||||
self.body.append(self.starttag(node, "div", **div_attrs))
|
||||
self.body.append(self.starttag(node, "iframe", **attrs))
|
||||
self.body.append("</iframe></div>")
|
||||
|
||||
|
||||
def depart_peertube_node(self, node):
|
||||
pass
|
||||
|
||||
|
||||
def visit_peertube_node_latex(self, node):
|
||||
instance = node["instance"]
|
||||
|
||||
if not (self.config.peertube_instance or instance):
|
||||
logger.warning(__("No peertube instance defined"))
|
||||
return
|
||||
|
||||
if instance is None:
|
||||
instance = self.config.peertube_instance
|
||||
|
||||
self.body.append(
|
||||
r'\begin{quote}\begin{center}\fbox{\url{' +
|
||||
instance +
|
||||
r'videos/watch/%s}}\end{center}\end{quote}' %
|
||||
node['id'])
|
||||
|
||||
|
||||
class PeerTube(Directive):
|
||||
has_content = True
|
||||
required_arguments = 1
|
||||
optional_arguments = 0
|
||||
final_argument_whitespace = False
|
||||
option_spec = {
|
||||
"instance": directives.unchanged,
|
||||
"width": directives.unchanged,
|
||||
"height": directives.unchanged,
|
||||
"aspect": directives.unchanged,
|
||||
}
|
||||
|
||||
def run(self):
|
||||
instance = self.options.get("instance")
|
||||
if "aspect" in self.options:
|
||||
aspect = self.options.get("aspect")
|
||||
m = re.match(r"(\d+):(\d+)", aspect)
|
||||
if m is None:
|
||||
raise ValueError("invalid aspect ratio %r" % aspect)
|
||||
aspect = tuple(int(x) for x in m.groups())
|
||||
else:
|
||||
aspect = None
|
||||
width = get_size(self.options, "width")
|
||||
height = get_size(self.options, "height")
|
||||
return [peertube(id=self.arguments[0], instance=instance, aspect=aspect, width=width, height=height)]
|
||||
|
||||
|
||||
def unsupported_visit_peertube(self, node):
|
||||
self.builder.warn('PeerTube: unsupported output format (node skipped)')
|
||||
raise nodes.SkipNode
|
||||
|
||||
|
||||
_NODE_VISITORS = {
|
||||
'html': (visit_peertube_node, depart_peertube_node),
|
||||
'latex': (visit_peertube_node_latex, depart_peertube_node),
|
||||
'man': (unsupported_visit_peertube, None),
|
||||
'texinfo': (unsupported_visit_peertube, None),
|
||||
'text': (unsupported_visit_peertube, None)
|
||||
}
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_node(peertube, **_NODE_VISITORS)
|
||||
app.add_directive("peertube", PeerTube)
|
||||
app.add_config_value('peertube_instance', "", True, [str])
|
||||
return {
|
||||
'parallel_read_safe': True,
|
||||
'parallel_write_safe': True,
|
||||
}
|
68
sphinx/template/exts/reference.py
Executable file
68
sphinx/template/exts/reference.py
Executable file
@ -0,0 +1,68 @@
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.nodes import Element, Node
|
||||
from docutils.parsers.rst import directives
|
||||
from docutils.parsers.rst.directives.admonitions import BaseAdmonition
|
||||
|
||||
from sphinx.locale import _
|
||||
from sphinx.util.docutils import SphinxDirective
|
||||
|
||||
|
||||
class refbox(nodes.Admonition, nodes.Element):
|
||||
pass
|
||||
|
||||
|
||||
def visit_refbox_node(self, node):
|
||||
self.visit_admonition(node)
|
||||
|
||||
|
||||
def depart_refbox_node(self, node):
|
||||
self.depart_admonition(node)
|
||||
|
||||
|
||||
class ReferenceDirective(BaseAdmonition, SphinxDirective):
|
||||
node_class = refbox
|
||||
has_content = True
|
||||
required_arguments = 0
|
||||
optional_arguments = 0
|
||||
final_argument_whitespace = False
|
||||
option_spec = {
|
||||
'class': directives.class_option,
|
||||
'name': directives.unchanged,
|
||||
}
|
||||
|
||||
def run(self):
|
||||
if not self.options.get('class'):
|
||||
self.options['class'] = ['refbox']
|
||||
|
||||
(reference,) = super().run()
|
||||
if isinstance(reference, nodes.system_message):
|
||||
return [reference]
|
||||
elif isinstance(reference, refbox):
|
||||
reference.insert(0, nodes.title(text=_('Reference')))
|
||||
reference['docname'] = self.env.docname
|
||||
self.add_name(reference)
|
||||
self.set_source_info(reference)
|
||||
self.state.document.note_explicit_target(reference)
|
||||
return [reference]
|
||||
else:
|
||||
raise RuntimeError # never reached here
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_node(
|
||||
refbox,
|
||||
html=(visit_refbox_node, depart_refbox_node),
|
||||
latex=(visit_refbox_node, depart_refbox_node),
|
||||
text=(visit_refbox_node, depart_refbox_node),
|
||||
man=(visit_refbox_node, depart_refbox_node),
|
||||
texinfo=(visit_refbox_node, depart_refbox_node),
|
||||
)
|
||||
|
||||
app.add_directive('reference', ReferenceDirective)
|
||||
|
||||
return {
|
||||
'version': '1.0',
|
||||
'parallel_read_safe': True,
|
||||
'parallel_write_safe': True,
|
||||
}
|
Loading…
Reference in New Issue
Block a user