mirror of
https://github.com/ChristianLight/tutor.git
synced 2024-05-30 04:40:49 +00:00
33e4f33afe
Now that the mypy bugs have been resolved, we are able to define more precisely and cleanly the types of Actions and Filters. Moreover, can now strongly type named actions and hooks (in consts.py). With such a strong typing, we get early alerts of hooks called with incorrect arguments, which is nothing short of awesome :) This change breaks the hooks API by removing the `context=...` argument. The reason for that is that we cannot insert arbitrary arguments between `P.args, P.kwargs`: https://peps.python.org/pep-0612/#the-components-of-a-paramspec > A function declared as def inner(a: A, b: B, *args: P.args, **kwargs: > P.kwargs) -> R has type Callable[Concatenate[A, B, P], R]. Placing > keyword-only parameters between the *args and **kwargs is forbidden. Getting the documentation to build in nitpicky mode is quite difficult... We need to add `nitpick_ignore` to the docs conf.py, otherwise sphinx complains about many missing class references. This, despite upgrading almost all doc requirements (except docutils).
131 lines
3.4 KiB
Python
131 lines
3.4 KiB
Python
import io
|
|
import os
|
|
import sys
|
|
from typing import Any, Dict, List
|
|
|
|
import docutils
|
|
import docutils.parsers.rst
|
|
|
|
# -- Project information -----------------------------------------------------
|
|
|
|
project = "Tutor"
|
|
copyright = ""
|
|
author = "Overhang.io"
|
|
|
|
# The short X.Y version
|
|
version = ""
|
|
# The full version, including alpha/beta/rc tags
|
|
release = ""
|
|
|
|
|
|
# -- General configuration ---------------------------------------------------
|
|
extensions = []
|
|
templates_path = ["_templates"]
|
|
source_suffix = ".rst"
|
|
master_doc = "index"
|
|
language = "en"
|
|
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
|
|
pygments_style = None
|
|
|
|
# Autodocumentation of modules
|
|
extensions.append("sphinx.ext.autodoc")
|
|
autodoc_typehints = "description"
|
|
# For the life of me I can't get the docs to compile in nitpicky mode without these
|
|
# ignore statements. You are most welcome to try and remove them.
|
|
nitpick_ignore = [
|
|
("py:class", "Config"),
|
|
("py:class", "click.Command"),
|
|
("py:class", "tutor.hooks.filters.P"),
|
|
("py:class", "tutor.hooks.filters.T"),
|
|
("py:class", "tutor.hooks.actions.P"),
|
|
]
|
|
|
|
# -- Sphinx-Click configuration
|
|
# https://sphinx-click.readthedocs.io/
|
|
extensions.append("sphinx_click")
|
|
# This is to avoid the addition of the local username to the docs
|
|
os.environ["HOME"] = "~"
|
|
# Make sure that sphinx-click can find the tutor module
|
|
sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
|
|
|
|
# -- Options for HTML output -------------------------------------------------
|
|
html_theme = "sphinx_rtd_theme"
|
|
html_theme_options = {
|
|
"logo_only": True,
|
|
"style_nav_header_background": "#EFEFEF",
|
|
}
|
|
html_context = {
|
|
"display_github": True,
|
|
"github_user": "overhangio",
|
|
"github_repo": "tutor",
|
|
"github_version": "master",
|
|
"conf_py_path": "/docs/",
|
|
}
|
|
html_static_path = ["img"]
|
|
|
|
# Custom settings
|
|
html_logo = "./img/tutor-logo.png"
|
|
html_favicon = "./img/favicon.png"
|
|
html_show_sourcelink = False
|
|
html_display_github = True
|
|
html_show_sphinx = False
|
|
html_github_user = "overhangio"
|
|
html_github_repo = "tutor"
|
|
# Images do not link to themselves
|
|
html_scaled_image_link = False
|
|
html_show_copyright = False
|
|
|
|
# Custom variables
|
|
here = os.path.abspath(os.path.dirname(__file__))
|
|
about: Dict[str, str] = {}
|
|
with io.open(
|
|
os.path.join(here, "..", "tutor", "__about__.py"), "rt", encoding="utf-8"
|
|
) as f:
|
|
exec(f.read(), about)
|
|
rst_prolog = """
|
|
.. |tutor_version| replace:: {}
|
|
""".format(
|
|
about["__version__"],
|
|
)
|
|
|
|
|
|
# Custom directives
|
|
def youtube(
|
|
_name: Any,
|
|
_args: Any,
|
|
_options: Any,
|
|
content: List[str],
|
|
_lineno: Any,
|
|
_contentOffset: Any,
|
|
_blockText: Any,
|
|
_state: Any,
|
|
_stateMachine: Any,
|
|
) -> Any:
|
|
"""Restructured text extension for inserting youtube embedded videos"""
|
|
if not content:
|
|
return []
|
|
video_id = content[0]
|
|
return [
|
|
docutils.nodes.raw(
|
|
"",
|
|
"""
|
|
<iframe width="560" height="315"
|
|
src="https://www.youtube-nocookie.com/embed/{video_id}"
|
|
frameborder="0"
|
|
allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
|
|
</iframe>""".format(
|
|
video_id=video_id
|
|
),
|
|
format="html",
|
|
)
|
|
]
|
|
|
|
|
|
# Tutor's own extension
|
|
sys.path.append(os.path.join(os.path.dirname(__file__), "_ext"))
|
|
extensions.append("tutordocs")
|
|
|
|
|
|
setattr(youtube, "content", True)
|
|
docutils.parsers.rst.directives.register_directive("youtube", youtube) # type: ignore
|