docs: use start-after/end-before for example includes

doc/source/examples.rst

@@ -19,7 +19,8 @@ simple stages to say "hello" and "goodbye".
 .. literalinclude:: ../../example/ex_0_the_basics.py
    :language: python
    :linenos:
-   :lines: 10-
+   :start-after: [start include-in-docs-examples]
+   :end-before: [end include-in-docs-examples]
    :emphasize-lines: 8-9,12-13,18-19
    :caption: ``example/ex_0_the_basics.py``
 
@@ -73,7 +74,8 @@ by adding the following to the ``MyScript`` class:
 .. literalinclude:: ../../example/ex_1_removing_the_retry_arguments.py
    :language: python
    :linenos:
-   :lines: 27-39
+   :start-after: [start include-in-docs-examples]
+   :end-before: [end include-in-docs-examples]
    :caption: ``example/ex_1_removing_the_retry_arguments.py``
 
 .. note::
@@ -109,7 +111,8 @@ that case, you can add the highlighted line:
 .. literalinclude:: ../../example/ex_2_running_certain_stages_by_default.py
    :language: python
    :linenos:
-   :lines: 27-29,41-42
+   :start-after: [start include-in-docs-examples]
+   :end-before: [end include-in-docs-examples]
    :emphasize-lines: 4
    :caption: ``example/ex_2_running_certain_stages_by_default.py``
 
@@ -138,7 +141,8 @@ Now let's see about adding some arguments to the parser beyond what
 .. literalinclude:: ../../example/ex_3_adding_arguments.py
    :language: python
    :linenos:
-   :lines: 32-34,45-57
+   :start-after: [start include-in-docs-examples-parser]
+   :end-before: [end include-in-docs-examples-parser]
    :emphasize-lines: 4-15
    :caption: ``example/ex_3_adding_arguments.py``
 
@@ -149,7 +153,8 @@ arguments to handle these new options.  You can do so by extending the
 .. literalinclude:: ../../example/ex_3_adding_arguments.py
    :language: python
    :linenos:
-   :lines: 59-70
+   :start-after: [start include-in-docs-examples-parse-args]
+   :end-before: [end include-in-docs-examples-parse-args]
    :caption: ``example/ex_3_adding_arguments.py``
 
 .. note::
@@ -166,7 +171,8 @@ the two stages to take them into account.
 .. literalinclude:: ../../example/ex_3_adding_arguments.py
    :language: python
    :linenos:
-   :lines: 20-30
+   :start-after: [start include-in-docs-examples-stage-usage]
+   :end-before: [end include-in-docs-examples-stage-usage]
    :emphasize-lines: 4,10
    :caption: ``example/ex_3_adding_arguments.py``
 
@@ -193,7 +199,8 @@ overridden in your subclasses.
 .. literalinclude:: ../../example/ex_4_customizing_stage_behavior.py
    :language: python
    :linenos:
-   :lines: 72-93
+   :start-after: [start include-in-docs-examples]
+   :end-before: [end include-in-docs-examples]
    :caption: ``example/ex_4_customizing_stage_behavior.py``
 
 .. note::
@@ -243,7 +250,8 @@ is the name of the stage as provided to the :ref:`StagedScript.stage()
 .. literalinclude:: ../../example/ex_5_customizing_individual_stages.py
    :language: python
    :linenos:
-   :lines: 95-112
+   :start-after: [start include-in-docs-examples]
+   :end-before: [end include-in-docs-examples]
    :caption: ``example/ex_5_customizing_individual_stages.py``
 
 Now when we run both stages we see:
@@ -281,7 +289,8 @@ flaky stage has been run.
 .. literalinclude:: ../../example/ex_6_creating_retryable_stages.py
    :language: python
    :linenos:
-   :lines: 23-37
+   :start-after: [start include-in-docs-examples-init]
+   :end-before: [end include-in-docs-examples-init]
    :emphasize-lines: 15
    :caption: ``example/ex_6_creating_retryable_stages.py``
 
@@ -293,7 +302,8 @@ something where a human would say, "Just try again," and setting
 .. literalinclude:: ../../example/ex_6_creating_retryable_stages.py
    :language: python
    :linenos:
-   :lines: 44-53
+   :start-after: [start include-in-docs-examples-body]
+   :end-before: [end include-in-docs-examples-body]
    :emphasize-lines: 7-8,10
    :caption: ``example/ex_6_creating_retryable_stages.py``
 
@@ -302,7 +312,8 @@ Next we need to adjust the parser to account for this new stage.
 .. literalinclude:: ../../example/ex_6_creating_retryable_stages.py
    :language: python
    :linenos:
-   :lines: 62-89
+   :start-after: [start include-in-docs-examples-parser]
+   :end-before: [end include-in-docs-examples-parser]
    :emphasize-lines: 13-14
    :caption: ``example/ex_6_creating_retryable_stages.py``
 
@@ -356,7 +367,8 @@ above, but you have the flexibility to :ref:`extend the behavior
 .. literalinclude:: ../../example/ex_7_customizing_the_summary.py
    :language: python
    :linenos:
-   :lines: 148-160
+   :start-after: [start include-in-docs-examples]
+   :end-before: [end include-in-docs-examples]
    :emphasize-lines: 6-9
    :caption: ``example/ex_7_customizing_the_summary.py``
 

doc/source/index.rst

@@ -99,7 +99,8 @@ Once the package is installed, you can simply
 .. literalinclude:: ../../example/ex_0_the_basics.py
    :language: python
    :linenos:
-   :lines: 10-
+   :start-after: [start include-in-docs-examples]
+   :end-before: [end include-in-docs-examples]
    :caption: ``example/ex_0_the_basics.py``
 
 Executing the script then yields

example/ex_0_the_basics.py

@@ -7,6 +7,7 @@
 
 # SPDX-License-Identifier: BSD-3-Clause
 
+# [start include-in-docs-examples]
 import sys
 
 from staged_script import StagedScript
@@ -33,3 +34,4 @@ def main(self, argv: list[str]) -> None:
 if __name__ == "__main__":
     my_script = MyScript({"hello", "goodbye"})
     my_script.main(sys.argv[1:])
+# [end include-in-docs-examples]

example/ex_1_removing_the_retry_arguments.py

@@ -24,6 +24,7 @@ def say_hello(self) -> None:
     def say_goodbye(self) -> None:
         self.run("echo 'Goodbye World'", shell=True)
 
+    # [start include-in-docs-examples]
     @functools.cached_property
     def parser(self) -> ArgumentParser:
         my_parser = super().parser
@@ -38,6 +39,8 @@ def parser(self) -> ArgumentParser:
         self.goodbye_retry_timeout_arg.help = argparse.SUPPRESS  # type: ignore[attr-defined]
         return my_parser
 
+    # [end include-in-docs-examples]
+
     def main(self, argv: list[str]) -> None:
         self.parse_args(argv)
         try:

example/ex_2_running_certain_stages_by_default.py

@@ -24,6 +24,7 @@ def say_hello(self) -> None:
     def say_goodbye(self) -> None:
         self.run("echo 'Goodbye World'", shell=True)
 
+    # [start include-in-docs-examples]
     @functools.cached_property
     def parser(self) -> ArgumentParser:
         my_parser = super().parser
@@ -41,6 +42,8 @@ def parser(self) -> ArgumentParser:
         my_parser.set_defaults(stage=list(self.stages))
         return my_parser
 
+    # [end include-in-docs-examples]
+
     def main(self, argv: list[str]) -> None:
         self.parse_args(argv)
         try:

example/ex_3_adding_arguments.py

@@ -17,6 +17,7 @@
 
 
 class MyScript(StagedScript):
+    # [start include-in-docs-examples-stage-usage]
     @StagedScript.stage("hello", "Greeting the user")
     def say_hello(self) -> None:
         self.run("echo 'Hello World'", shell=True)
@@ -29,6 +30,9 @@ def say_goodbye(self) -> None:
             "Some flag was " + ("not " if not self.flag else "") + "set!"
         )
 
+    # [end include-in-docs-examples-stage-usage]
+
+    # [start include-in-docs-examples-parser]
     @functools.cached_property
     def parser(self) -> ArgumentParser:
         my_parser = super().parser
@@ -56,6 +60,9 @@ def parser(self) -> ArgumentParser:
         )
         return my_parser
 
+    # [end include-in-docs-examples-parser]
+
+    # [start include-in-docs-examples-parse-args]
     def parse_args(self, argv: list[str]) -> None:
         # The base class saves the parsed arguments as `self.args`.
         super().parse_args(argv)
@@ -69,6 +76,8 @@ def parse_args(self, argv: list[str]) -> None:
         # not.
         self.args.some_file = self.args.some_file.resolve()
 
+    # [end include-in-docs-examples-parse-args]
+
     def main(self, argv: list[str]) -> None:
         self.parse_args(argv)
         try:

example/ex_4_customizing_stage_behavior.py

@@ -69,6 +69,7 @@ def parse_args(self, argv: list[str]) -> None:
         # not.
         self.args.some_file = self.args.some_file.resolve()
 
+    # [start include-in-docs-examples]
     def _run_pre_stage_actions(self) -> None:
         # You can extend the default implementation by calling it via
         # `super()` first.
@@ -92,6 +93,8 @@ def _run_post_stage_actions(self) -> None:
             "Checking to make sure all is well after running the stage..."
         )
 
+    # [end include-in-docs-examples]
+
     def main(self, argv: list[str]) -> None:
         self.parse_args(argv)
         try:

example/ex_5_customizing_individual_stages.py

@@ -92,6 +92,7 @@ def _run_post_stage_actions(self) -> None:
             "Checking to make sure all is well after running the stage..."
         )
 
+    # [start include-in-docs-examples]
     def _begin_stage_hello(self, heading: str) -> None:
         # You can use whatever `_begin_stage()` method already exists,
         # either whatever's been overridden or extended in the current
@@ -111,6 +112,8 @@ def _end_stage_goodbye(self) -> None:
         # or `super()` calls to the default method for the corresponding
         # phase, if you like.
 
+    # [end include-in-docs-examples]
+
     def main(self, argv: list[str]) -> None:
         self.parse_args(argv)
         try:

example/ex_6_creating_retryable_stages.py

@@ -19,6 +19,7 @@
 
 
 class MyScript(StagedScript):
+    # [start include-in-docs-examples-init]
     def __init__(
         self,
         stages: set[str],
@@ -35,11 +36,14 @@ def __init__(
         )
         self.num_times_flaky_run = 0
 
+    # [end include-in-docs-examples-init]
+
     @StagedScript.stage("hello", "Greeting the user")
     def say_hello(self) -> None:
         self.run("echo 'Hello World'", shell=True)
         self.console.log(f"Processing file:  {self.args.some_file}")
 
+    # [start include-in-docs-examples-body]
     @StagedScript.stage("flaky", "Trying an error-prone operation")
     def try_error_prone_operation(self) -> None:
         self.num_times_flaky_run += 1
@@ -51,13 +55,16 @@ def try_error_prone_operation(self) -> None:
         self.console.log("[green]Thank goodness, everything worked this time.")
         self.script_success = True
 
+    # [end include-in-docs-examples-body]
+
     @StagedScript.stage("goodbye", "Bidding farewell")
     def say_goodbye(self) -> None:
         self.run("echo 'Goodbye World'", shell=True)
         self.console.log(
             "Some flag was " + ("not " if not self.flag else "") + "set!"
         )
 
+    # [start include-in-docs-examples-parser]
     @functools.cached_property
     def parser(self) -> ArgumentParser:
         my_parser = super().parser
@@ -87,6 +94,8 @@ def parser(self) -> ArgumentParser:
         )
         return my_parser
 
+    # [end include-in-docs-examples-parser]
+
     def parse_args(self, argv: list[str]) -> None:
         # The base class saves the parsed arguments as `self.args`.
         super().parse_args(argv)

example/ex_7_customizing_the_summary.py

@@ -144,6 +144,7 @@ def _end_stage_goodbye(self) -> None:
         # or `super()` calls to the default method for the corresponding
         # phase, if you like.
 
+    # [start include-in-docs-examples]
     def print_script_execution_summary(
         self,
         extra_sections: dict[str, str] | None = None,
@@ -158,6 +159,8 @@ def print_script_execution_summary(
             extras |= extra_sections
         super().print_script_execution_summary(extra_sections=extras)
 
+    # [end include-in-docs-examples]
+
     def main(self, argv: list[str]) -> None:
         self.parse_args(argv)
         try: