summaryrefslogtreecommitdiffstats
path: root/doc/development/tutorials
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/tutorials')
-rw-r--r--doc/development/tutorials/examples/autodoc_intenum.py19
-rw-r--r--doc/development/tutorials/examples/helloworld.py8
-rw-r--r--doc/development/tutorials/examples/recipe.py46
-rw-r--r--doc/development/tutorials/examples/todo.py34
-rw-r--r--doc/development/tutorials/recipe.rst6
5 files changed, 61 insertions, 52 deletions
diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py
index 75fa204..c52bb4c 100644
--- a/doc/development/tutorials/examples/autodoc_intenum.py
+++ b/doc/development/tutorials/examples/autodoc_intenum.py
@@ -19,9 +19,9 @@ class IntEnumDocumenter(ClassDocumenter):
option_spec['hex'] = bool_option
@classmethod
- def can_document_member(cls,
- member: Any, membername: str,
- isattr: bool, parent: Any) -> bool:
+ def can_document_member(
+ cls, member: Any, membername: str, isattr: bool, parent: Any
+ ) -> bool:
try:
return issubclass(member, IntEnum)
except TypeError:
@@ -31,11 +31,11 @@ class IntEnumDocumenter(ClassDocumenter):
super().add_directive_header(sig)
self.add_line(' :final:', self.get_sourcename())
- def add_content(self,
- more_content: StringList | None,
- no_docstring: bool = False,
- ) -> None:
-
+ def add_content(
+ self,
+ more_content: StringList | None,
+ no_docstring: bool = False,
+ ) -> None:
super().add_content(more_content, no_docstring)
source_name = self.get_sourcename()
@@ -48,8 +48,7 @@ class IntEnumDocumenter(ClassDocumenter):
if use_hex:
the_member_value = hex(the_member_value)
- self.add_line(
- f"**{the_member_name}**: {the_member_value}", source_name)
+ self.add_line(f'**{the_member_name}**: {the_member_value}', source_name)
self.add_line('', source_name)
diff --git a/doc/development/tutorials/examples/helloworld.py b/doc/development/tutorials/examples/helloworld.py
index d6d81fd..da29562 100644
--- a/doc/development/tutorials/examples/helloworld.py
+++ b/doc/development/tutorials/examples/helloworld.py
@@ -1,16 +1,18 @@
from docutils import nodes
from docutils.parsers.rst import Directive
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
-class HelloWorld(Directive):
+class HelloWorld(Directive):
def run(self):
paragraph_node = nodes.paragraph(text='Hello World!')
return [paragraph_node]
-def setup(app):
- app.add_directive("helloworld", HelloWorld)
+def setup(app: Sphinx) -> ExtensionMetadata:
+ app.add_directive('helloworld', HelloWorld)
return {
'version': '0.1',
diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py
index c7ebf2a..28d25f2 100644
--- a/doc/development/tutorials/examples/recipe.py
+++ b/doc/development/tutorials/examples/recipe.py
@@ -3,10 +3,12 @@ from collections import defaultdict
from docutils.parsers.rst import directives
from sphinx import addnodes
+from sphinx.application import Sphinx
from sphinx.directives import ObjectDescription
from sphinx.domains import Domain, Index
from sphinx.roles import XRefRole
from sphinx.util.nodes import make_refnode
+from sphinx.util.typing import ExtensionMetadata
class RecipeDirective(ObjectDescription):
@@ -25,8 +27,7 @@ class RecipeDirective(ObjectDescription):
def add_target_and_index(self, name_cls, sig, signode):
signode['ids'].append('recipe' + '-' + sig)
if 'contains' in self.options:
- ingredients = [
- x.strip() for x in self.options.get('contains').split(',')]
+ ingredients = [x.strip() for x in self.options.get('contains').split(',')]
recipes = self.env.get_domain('recipe')
recipes.add_recipe(sig, ingredients)
@@ -42,9 +43,10 @@ class IngredientIndex(Index):
def generate(self, docnames=None):
content = defaultdict(list)
- recipes = {name: (dispname, typ, docname, anchor)
- for name, dispname, typ, docname, anchor, _
- in self.domain.get_objects()}
+ recipes = {
+ name: (dispname, typ, docname, anchor)
+ for name, dispname, typ, docname, anchor, _ in self.domain.get_objects()
+ }
recipe_ingredients = self.domain.data['recipe_ingredients']
ingredient_recipes = defaultdict(list)
@@ -60,8 +62,7 @@ class IngredientIndex(Index):
for ingredient, recipe_names in ingredient_recipes.items():
for recipe_name in recipe_names:
dispname, typ, docname, anchor = recipes[recipe_name]
- content[ingredient].append(
- (dispname, 0, docname, anchor, docname, '', typ))
+ content[ingredient].append((dispname, 0, docname, anchor, docname, '', typ))
# convert the dict to the sorted list of tuples expected
content = sorted(content.items())
@@ -88,8 +89,15 @@ class RecipeIndex(Index):
#
# name, subtype, docname, anchor, extra, qualifier, description
for _name, dispname, typ, docname, anchor, _priority in recipes:
- content[dispname[0].lower()].append(
- (dispname, 0, docname, anchor, docname, '', typ))
+ content[dispname[0].lower()].append((
+ dispname,
+ 0,
+ docname,
+ anchor,
+ docname,
+ '',
+ typ,
+ ))
# convert the dict to the sorted list of tuples expected
content = sorted(content.items())
@@ -98,7 +106,6 @@ class RecipeIndex(Index):
class RecipeDomain(Domain):
-
name = 'recipe'
label = 'Recipe Sample'
roles = {
@@ -122,18 +129,18 @@ class RecipeDomain(Domain):
def get_objects(self):
yield from self.data['recipes']
- def resolve_xref(self, env, fromdocname, builder, typ, target, node,
- contnode):
- match = [(docname, anchor)
- for name, sig, typ, docname, anchor, prio
- in self.get_objects() if sig == target]
+ def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
+ match = [
+ (docname, anchor)
+ for name, sig, typ, docname, anchor, prio in self.get_objects()
+ if sig == target
+ ]
if len(match) > 0:
todocname = match[0][0]
targ = match[0][1]
- return make_refnode(builder, fromdocname, todocname, targ,
- contnode, targ)
+ return make_refnode(builder, fromdocname, todocname, targ, contnode, targ)
else:
print('Awww, found nothing')
return None
@@ -145,11 +152,10 @@ class RecipeDomain(Domain):
self.data['recipe_ingredients'][name] = ingredients
# name, dispname, type, docname, anchor, priority
- self.data['recipes'].append(
- (name, signature, 'Recipe', self.env.docname, anchor, 0))
+ self.data['recipes'].append((name, signature, 'Recipe', self.env.docname, anchor, 0))
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
app.add_domain(RecipeDomain)
return {
diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py
index 15368f4..2baac5c 100644
--- a/doc/development/tutorials/examples/todo.py
+++ b/doc/development/tutorials/examples/todo.py
@@ -1,8 +1,10 @@
from docutils import nodes
from docutils.parsers.rst import Directive
+from sphinx.application import Sphinx
from sphinx.locale import _
from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
class todo(nodes.Admonition, nodes.Element):
@@ -22,13 +24,11 @@ def depart_todo_node(self, node):
class TodolistDirective(Directive):
-
def run(self):
return [todolist('')]
class TodoDirective(SphinxDirective):
-
# this enables content in the directive
has_content = True
@@ -57,8 +57,7 @@ def purge_todos(app, env, docname):
if not hasattr(env, 'todo_all_todos'):
return
- env.todo_all_todos = [todo for todo in env.todo_all_todos
- if todo['docname'] != docname]
+ env.todo_all_todos = [todo for todo in env.todo_all_todos if todo['docname'] != docname]
def merge_todos(app, env, docnames, other):
@@ -90,37 +89,40 @@ def process_todo_nodes(app, doctree, fromdocname):
for todo_info in env.todo_all_todos:
para = nodes.paragraph()
filename = env.doc2path(todo_info['docname'], base=None)
- description = (
- _('(The original entry is located in %s, line %d and can be found ') %
- (filename, todo_info['lineno']))
+ description = _(
+ '(The original entry is located in %s, line %d and can be found '
+ ) % (filename, todo_info['lineno'])
para += nodes.Text(description)
# Create a reference
newnode = nodes.reference('', '')
innernode = nodes.emphasis(_('here'), _('here'))
newnode['refdocname'] = todo_info['docname']
- newnode['refuri'] = app.builder.get_relative_uri(
- fromdocname, todo_info['docname'])
+ newnode['refuri'] = app.builder.get_relative_uri(fromdocname, todo_info['docname'])
newnode['refuri'] += '#' + todo_info['target']['refid']
newnode.append(innernode)
para += newnode
para += nodes.Text('.)')
# Insert into the todolist
- content.append(todo_info['todo'])
- content.append(para)
+ content.extend((
+ todo_info['todo'],
+ para,
+ ))
node.replace_self(content)
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('todo_include_todos', False, 'html')
app.add_node(todolist)
- app.add_node(todo,
- html=(visit_todo_node, depart_todo_node),
- latex=(visit_todo_node, depart_todo_node),
- text=(visit_todo_node, depart_todo_node))
+ app.add_node(
+ todo,
+ html=(visit_todo_node, depart_todo_node),
+ latex=(visit_todo_node, depart_todo_node),
+ text=(visit_todo_node, depart_todo_node),
+ )
app.add_directive('todo', TodoDirective)
app.add_directive('todolist', TodolistDirective)
diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst
index 1ed428a..683cc8c 100644
--- a/doc/development/tutorials/recipe.rst
+++ b/doc/development/tutorials/recipe.rst
@@ -179,9 +179,9 @@ hook the various parts of our extension into Sphinx. Let's look at the
This looks a little different to what we're used to seeing. There are no calls
to :meth:`~Sphinx.add_directive` or even :meth:`~Sphinx.add_role`. Instead, we
have a single call to :meth:`~Sphinx.add_domain` followed by some
-initialization of the :ref:`standard domain <domains-std>`. This is because we
-had already registered our directives, roles and indexes as part of the
-directive itself.
+initialization of the :doc:`standard domain </usage/domains/standard>`.
+This is because we had already registered our directives,
+roles and indexes as part of the directive itself.
Using the extension