diff options
Diffstat (limited to 'doc/development/tutorials')
| -rw-r--r-- | doc/development/tutorials/examples/autodoc_intenum.py | 19 | ||||
| -rw-r--r-- | doc/development/tutorials/examples/helloworld.py | 8 | ||||
| -rw-r--r-- | doc/development/tutorials/examples/recipe.py | 46 | ||||
| -rw-r--r-- | doc/development/tutorials/examples/todo.py | 34 | ||||
| -rw-r--r-- | doc/development/tutorials/recipe.rst | 6 |
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 |