Skip to content

Commit 8428326

Browse files
committed
docs(argparse_exemplar): Add doctest to _create_example_section
Add working doctests demonstrating: - Basic section creation from definition nodes - Page prefix for unique section IDs across docs - Category-prefixed examples with descriptive IDs/titles This helper function creates docutils section nodes and is straightforward to test, unlike complex visitor traversals.
1 parent 40abbf3 commit 8428326

1 file changed

Lines changed: 27 additions & 0 deletions

File tree

docs/_ext/argparse_exemplar.py

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,33 @@ def _create_example_section(
516516
-------
517517
nodes.section
518518
A section node with title and code blocks.
519+
520+
Examples
521+
--------
522+
Create a section from a definition node containing example commands:
523+
524+
>>> from docutils import nodes
525+
>>> def_node = nodes.definition()
526+
>>> def_node += nodes.paragraph(text="myapp sync")
527+
>>> section = _create_example_section("examples:", def_node)
528+
>>> section["ids"]
529+
['examples']
530+
>>> section[0].astext()
531+
'Examples'
532+
533+
With a page prefix for uniqueness across documentation pages:
534+
535+
>>> section = _create_example_section("examples:", def_node, page_prefix="sync")
536+
>>> section["ids"]
537+
['sync-examples']
538+
539+
Category-prefixed examples create descriptive section IDs:
540+
541+
>>> section = _create_example_section("Machine-readable output examples:", def_node)
542+
>>> section["ids"]
543+
['machine-readable-output-examples']
544+
>>> section[0].astext()
545+
'Machine-Readable Output Examples'
519546
"""
520547
config = config or ExemplarConfig()
521548
section_id = make_section_id(

0 commit comments

Comments
 (0)