From 157b175b9c980ddf441623d22f8ad971bc7f9c39 Mon Sep 17 00:00:00 2001 From: lavafreak Date: Thu, 4 Jun 2026 11:52:03 -0600 Subject: [PATCH 1/3] docs: use start-after/end-before for examples --- doc/source/examples.rst | 36 ++++++++++++------- doc/source/index.rst | 3 +- example/ex_0_the_basics.py | 2 ++ example/ex_1_removing_the_retry_arguments.py | 2 ++ .../ex_2_running_certain_stages_by_default.py | 2 ++ example/ex_3_adding_arguments.py | 6 ++++ example/ex_4_customizing_stage_behavior.py | 2 ++ example/ex_5_customizing_individual_stages.py | 2 ++ example/ex_6_creating_retryable_stages.py | 6 ++++ example/ex_7_customizing_the_summary.py | 2 ++ 10 files changed, 50 insertions(+), 13 deletions(-) diff --git a/doc/source/examples.rst b/doc/source/examples.rst index 3ba1064..ac5f769 100644 --- a/doc/source/examples.rst +++ b/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 the-basics] + :end-before: [end the-basics] :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 removing-retry-arguments] + :end-before: [end removing-retry-arguments] :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 running-stages-by-default] + :end-before: [end running-stages-by-default] :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 adding-arguments-parser] + :end-before: [end adding-arguments-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 adding-arguments-parse-args] + :end-before: [end adding-arguments-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 adding-arguments-stage-usage] + :end-before: [end adding-arguments-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 customizing-stage-behavior] + :end-before: [end customizing-stage-behavior] :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 customizing-individual-stages] + :end-before: [end customizing-individual-stages] :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 retryable-stage-init] + :end-before: [end retryable-stage-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 retryable-stage-body] + :end-before: [end retryable-stage-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 retryable-stage-parser] + :end-before: [end retryable-stage-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 customizing-the-summary] + :end-before: [end customizing-the-summary] :emphasize-lines: 6-9 :caption: ``example/ex_7_customizing_the_summary.py`` diff --git a/doc/source/index.rst b/doc/source/index.rst index b362e0e..3352579 100644 --- a/doc/source/index.rst +++ b/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 the-basics] + :end-before: [end the-basics] :caption: ``example/ex_0_the_basics.py`` Executing the script then yields diff --git a/example/ex_0_the_basics.py b/example/ex_0_the_basics.py index 1f1c64e..e578be7 100755 --- a/example/ex_0_the_basics.py +++ b/example/ex_0_the_basics.py @@ -7,6 +7,7 @@ # SPDX-License-Identifier: BSD-3-Clause +# [start the-basics] 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 the-basics] diff --git a/example/ex_1_removing_the_retry_arguments.py b/example/ex_1_removing_the_retry_arguments.py index dc8a167..7687ead 100755 --- a/example/ex_1_removing_the_retry_arguments.py +++ b/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 removing-retry-arguments] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -37,6 +38,7 @@ def parser(self) -> ArgumentParser: self.goodbye_retry_delay_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] self.goodbye_retry_timeout_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] return my_parser + # [end removing-retry-arguments] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_2_running_certain_stages_by_default.py b/example/ex_2_running_certain_stages_by_default.py index 683674e..7813e1d 100755 --- a/example/ex_2_running_certain_stages_by_default.py +++ b/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 running-stages-by-default] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -40,6 +41,7 @@ def parser(self) -> ArgumentParser: self.goodbye_retry_timeout_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] my_parser.set_defaults(stage=list(self.stages)) return my_parser + # [end running-stages-by-default] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_3_adding_arguments.py b/example/ex_3_adding_arguments.py index 282b931..a273c4b 100755 --- a/example/ex_3_adding_arguments.py +++ b/example/ex_3_adding_arguments.py @@ -17,6 +17,7 @@ class MyScript(StagedScript): + # [start adding-arguments-stage-usage] @StagedScript.stage("hello", "Greeting the user") def say_hello(self) -> None: self.run("echo 'Hello World'", shell=True) @@ -28,7 +29,9 @@ def say_goodbye(self) -> None: self.console.log( "Some flag was " + ("not " if not self.flag else "") + "set!" ) + # [end adding-arguments-stage-usage] + # [start adding-arguments-parser] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -55,7 +58,9 @@ def parser(self) -> ArgumentParser: help="Some flag your users can toggle on if they like.", ) return my_parser + # [end adding-arguments-parser] + # [start adding-arguments-parse-args] def parse_args(self, argv: list[str]) -> None: # The base class saves the parsed arguments as `self.args`. super().parse_args(argv) @@ -68,6 +73,7 @@ def parse_args(self, argv: list[str]) -> None: # arguments, whether you save them as instance attributes or # not. self.args.some_file = self.args.some_file.resolve() + # [end adding-arguments-parse-args] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_4_customizing_stage_behavior.py b/example/ex_4_customizing_stage_behavior.py index f6e507c..a7d9d63 100755 --- a/example/ex_4_customizing_stage_behavior.py +++ b/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 customizing-stage-behavior] def _run_pre_stage_actions(self) -> None: # You can extend the default implementation by calling it via # `super()` first. @@ -91,6 +92,7 @@ def _run_post_stage_actions(self) -> None: self.console.log( "Checking to make sure all is well after running the stage..." ) + # [end customizing-stage-behavior] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_5_customizing_individual_stages.py b/example/ex_5_customizing_individual_stages.py index 7cf63b8..d93ba75 100755 --- a/example/ex_5_customizing_individual_stages.py +++ b/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 customizing-individual-stages] 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 @@ -110,6 +111,7 @@ def _end_stage_goodbye(self) -> None: # You can also override things completely by omitting any `self` # or `super()` calls to the default method for the corresponding # phase, if you like. + # [end customizing-individual-stages] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_6_creating_retryable_stages.py b/example/ex_6_creating_retryable_stages.py index 5b79bb0..267b098 100755 --- a/example/ex_6_creating_retryable_stages.py +++ b/example/ex_6_creating_retryable_stages.py @@ -19,6 +19,7 @@ class MyScript(StagedScript): + # [start retryable-stage-init] def __init__( self, stages: set[str], @@ -34,12 +35,14 @@ def __init__( print_commands=print_commands, ) self.num_times_flaky_run = 0 + # [end retryable-stage-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 retryable-stage-body] @StagedScript.stage("flaky", "Trying an error-prone operation") def try_error_prone_operation(self) -> None: self.num_times_flaky_run += 1 @@ -50,6 +53,7 @@ def try_error_prone_operation(self) -> None: raise RetryStage self.console.log("[green]Thank goodness, everything worked this time.") self.script_success = True + # [end retryable-stage-body] @StagedScript.stage("goodbye", "Bidding farewell") def say_goodbye(self) -> None: @@ -58,6 +62,7 @@ def say_goodbye(self) -> None: "Some flag was " + ("not " if not self.flag else "") + "set!" ) + # [start retryable-stage-parser] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -86,6 +91,7 @@ def parser(self) -> ArgumentParser: help="Some flag your users can toggle on if they like.", ) return my_parser + # [end retryable-stage-parser] def parse_args(self, argv: list[str]) -> None: # The base class saves the parsed arguments as `self.args`. diff --git a/example/ex_7_customizing_the_summary.py b/example/ex_7_customizing_the_summary.py index 2a21d5c..cd96808 100755 --- a/example/ex_7_customizing_the_summary.py +++ b/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 customizing-the-summary] def print_script_execution_summary( self, extra_sections: dict[str, str] | None = None, @@ -157,6 +158,7 @@ def print_script_execution_summary( if extra_sections is not None: extras |= extra_sections super().print_script_execution_summary(extra_sections=extras) + # [end customizing-the-summary] def main(self, argv: list[str]) -> None: self.parse_args(argv) From 2722b7eb6418429830aaeacd649c9253afaf3d42 Mon Sep 17 00:00:00 2001 From: lavafreak Date: Thu, 4 Jun 2026 13:07:21 -0600 Subject: [PATCH 2/3] docs: use consistent include marker names --- doc/source/examples.rst | 48 +++++++++---------- doc/source/index.rst | 4 +- example/ex_0_the_basics.py | 4 +- example/ex_1_removing_the_retry_arguments.py | 4 +- .../ex_2_running_certain_stages_by_default.py | 4 +- example/ex_3_adding_arguments.py | 12 ++--- example/ex_4_customizing_stage_behavior.py | 4 +- example/ex_5_customizing_individual_stages.py | 4 +- example/ex_6_creating_retryable_stages.py | 12 ++--- example/ex_7_customizing_the_summary.py | 4 +- 10 files changed, 50 insertions(+), 50 deletions(-) diff --git a/doc/source/examples.rst b/doc/source/examples.rst index ac5f769..8ec1793 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -19,8 +19,8 @@ simple stages to say "hello" and "goodbye". .. literalinclude:: ../../example/ex_0_the_basics.py :language: python :linenos: - :start-after: [start the-basics] - :end-before: [end the-basics] + :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`` @@ -74,8 +74,8 @@ by adding the following to the ``MyScript`` class: .. literalinclude:: ../../example/ex_1_removing_the_retry_arguments.py :language: python :linenos: - :start-after: [start removing-retry-arguments] - :end-before: [end removing-retry-arguments] + :start-after: [start include-in-docs-examples] + :end-before: [end include-in-docs-examples] :caption: ``example/ex_1_removing_the_retry_arguments.py`` .. note:: @@ -111,8 +111,8 @@ that case, you can add the highlighted line: .. literalinclude:: ../../example/ex_2_running_certain_stages_by_default.py :language: python :linenos: - :start-after: [start running-stages-by-default] - :end-before: [end running-stages-by-default] + :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`` @@ -141,8 +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: - :start-after: [start adding-arguments-parser] - :end-before: [end adding-arguments-parser] + :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`` @@ -153,8 +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: - :start-after: [start adding-arguments-parse-args] - :end-before: [end adding-arguments-parse-args] + :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:: @@ -171,8 +171,8 @@ the two stages to take them into account. .. literalinclude:: ../../example/ex_3_adding_arguments.py :language: python :linenos: - :start-after: [start adding-arguments-stage-usage] - :end-before: [end adding-arguments-stage-usage] + :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`` @@ -199,8 +199,8 @@ overridden in your subclasses. .. literalinclude:: ../../example/ex_4_customizing_stage_behavior.py :language: python :linenos: - :start-after: [start customizing-stage-behavior] - :end-before: [end customizing-stage-behavior] + :start-after: [start include-in-docs-examples] + :end-before: [end include-in-docs-examples] :caption: ``example/ex_4_customizing_stage_behavior.py`` .. note:: @@ -250,8 +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: - :start-after: [start customizing-individual-stages] - :end-before: [end customizing-individual-stages] + :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: @@ -289,8 +289,8 @@ flaky stage has been run. .. literalinclude:: ../../example/ex_6_creating_retryable_stages.py :language: python :linenos: - :start-after: [start retryable-stage-init] - :end-before: [end retryable-stage-init] + :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`` @@ -302,8 +302,8 @@ something where a human would say, "Just try again," and setting .. literalinclude:: ../../example/ex_6_creating_retryable_stages.py :language: python :linenos: - :start-after: [start retryable-stage-body] - :end-before: [end retryable-stage-body] + :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`` @@ -312,8 +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: - :start-after: [start retryable-stage-parser] - :end-before: [end retryable-stage-parser] + :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`` @@ -367,8 +367,8 @@ above, but you have the flexibility to :ref:`extend the behavior .. literalinclude:: ../../example/ex_7_customizing_the_summary.py :language: python :linenos: - :start-after: [start customizing-the-summary] - :end-before: [end customizing-the-summary] + :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`` diff --git a/doc/source/index.rst b/doc/source/index.rst index 3352579..d40c99e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -99,8 +99,8 @@ Once the package is installed, you can simply .. literalinclude:: ../../example/ex_0_the_basics.py :language: python :linenos: - :start-after: [start the-basics] - :end-before: [end the-basics] + :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 diff --git a/example/ex_0_the_basics.py b/example/ex_0_the_basics.py index e578be7..4f6e5c5 100755 --- a/example/ex_0_the_basics.py +++ b/example/ex_0_the_basics.py @@ -7,7 +7,7 @@ # SPDX-License-Identifier: BSD-3-Clause -# [start the-basics] +# [start include-in-docs-examples] import sys from staged_script import StagedScript @@ -34,4 +34,4 @@ def main(self, argv: list[str]) -> None: if __name__ == "__main__": my_script = MyScript({"hello", "goodbye"}) my_script.main(sys.argv[1:]) -# [end the-basics] +# [end include-in-docs-examples] diff --git a/example/ex_1_removing_the_retry_arguments.py b/example/ex_1_removing_the_retry_arguments.py index 7687ead..ad336a1 100755 --- a/example/ex_1_removing_the_retry_arguments.py +++ b/example/ex_1_removing_the_retry_arguments.py @@ -24,7 +24,7 @@ def say_hello(self) -> None: def say_goodbye(self) -> None: self.run("echo 'Goodbye World'", shell=True) - # [start removing-retry-arguments] + # [start include-in-docs-examples] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -38,7 +38,7 @@ def parser(self) -> ArgumentParser: self.goodbye_retry_delay_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] self.goodbye_retry_timeout_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] return my_parser - # [end removing-retry-arguments] + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_2_running_certain_stages_by_default.py b/example/ex_2_running_certain_stages_by_default.py index 7813e1d..6c66ff1 100755 --- a/example/ex_2_running_certain_stages_by_default.py +++ b/example/ex_2_running_certain_stages_by_default.py @@ -24,7 +24,7 @@ def say_hello(self) -> None: def say_goodbye(self) -> None: self.run("echo 'Goodbye World'", shell=True) - # [start running-stages-by-default] + # [start include-in-docs-examples] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -41,7 +41,7 @@ def parser(self) -> ArgumentParser: self.goodbye_retry_timeout_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] my_parser.set_defaults(stage=list(self.stages)) return my_parser - # [end running-stages-by-default] + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_3_adding_arguments.py b/example/ex_3_adding_arguments.py index a273c4b..2fbf586 100755 --- a/example/ex_3_adding_arguments.py +++ b/example/ex_3_adding_arguments.py @@ -17,7 +17,7 @@ class MyScript(StagedScript): - # [start adding-arguments-stage-usage] + # [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,9 +29,9 @@ def say_goodbye(self) -> None: self.console.log( "Some flag was " + ("not " if not self.flag else "") + "set!" ) - # [end adding-arguments-stage-usage] + # [end include-in-docs-examples-stage-usage] - # [start adding-arguments-parser] + # [start include-in-docs-examples-parser] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -58,9 +58,9 @@ def parser(self) -> ArgumentParser: help="Some flag your users can toggle on if they like.", ) return my_parser - # [end adding-arguments-parser] + # [end include-in-docs-examples-parser] - # [start adding-arguments-parse-args] + # [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) @@ -73,7 +73,7 @@ def parse_args(self, argv: list[str]) -> None: # arguments, whether you save them as instance attributes or # not. self.args.some_file = self.args.some_file.resolve() - # [end adding-arguments-parse-args] + # [end include-in-docs-examples-parse-args] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_4_customizing_stage_behavior.py b/example/ex_4_customizing_stage_behavior.py index a7d9d63..9a9ab90 100755 --- a/example/ex_4_customizing_stage_behavior.py +++ b/example/ex_4_customizing_stage_behavior.py @@ -69,7 +69,7 @@ def parse_args(self, argv: list[str]) -> None: # not. self.args.some_file = self.args.some_file.resolve() - # [start customizing-stage-behavior] + # [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,7 +92,7 @@ def _run_post_stage_actions(self) -> None: self.console.log( "Checking to make sure all is well after running the stage..." ) - # [end customizing-stage-behavior] + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_5_customizing_individual_stages.py b/example/ex_5_customizing_individual_stages.py index d93ba75..df30d95 100755 --- a/example/ex_5_customizing_individual_stages.py +++ b/example/ex_5_customizing_individual_stages.py @@ -92,7 +92,7 @@ def _run_post_stage_actions(self) -> None: "Checking to make sure all is well after running the stage..." ) - # [start customizing-individual-stages] + # [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,7 +111,7 @@ def _end_stage_goodbye(self) -> None: # You can also override things completely by omitting any `self` # or `super()` calls to the default method for the corresponding # phase, if you like. - # [end customizing-individual-stages] + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: self.parse_args(argv) diff --git a/example/ex_6_creating_retryable_stages.py b/example/ex_6_creating_retryable_stages.py index 267b098..3eb0fb2 100755 --- a/example/ex_6_creating_retryable_stages.py +++ b/example/ex_6_creating_retryable_stages.py @@ -19,7 +19,7 @@ class MyScript(StagedScript): - # [start retryable-stage-init] + # [start include-in-docs-examples-init] def __init__( self, stages: set[str], @@ -35,14 +35,14 @@ def __init__( print_commands=print_commands, ) self.num_times_flaky_run = 0 - # [end retryable-stage-init] + # [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 retryable-stage-body] + # [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 @@ -53,7 +53,7 @@ def try_error_prone_operation(self) -> None: raise RetryStage self.console.log("[green]Thank goodness, everything worked this time.") self.script_success = True - # [end retryable-stage-body] + # [end include-in-docs-examples-body] @StagedScript.stage("goodbye", "Bidding farewell") def say_goodbye(self) -> None: @@ -62,7 +62,7 @@ def say_goodbye(self) -> None: "Some flag was " + ("not " if not self.flag else "") + "set!" ) - # [start retryable-stage-parser] + # [start include-in-docs-examples-parser] @functools.cached_property def parser(self) -> ArgumentParser: my_parser = super().parser @@ -91,7 +91,7 @@ def parser(self) -> ArgumentParser: help="Some flag your users can toggle on if they like.", ) return my_parser - # [end retryable-stage-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`. diff --git a/example/ex_7_customizing_the_summary.py b/example/ex_7_customizing_the_summary.py index cd96808..9fd958c 100755 --- a/example/ex_7_customizing_the_summary.py +++ b/example/ex_7_customizing_the_summary.py @@ -144,7 +144,7 @@ def _end_stage_goodbye(self) -> None: # or `super()` calls to the default method for the corresponding # phase, if you like. - # [start customizing-the-summary] + # [start include-in-docs-examples] def print_script_execution_summary( self, extra_sections: dict[str, str] | None = None, @@ -158,7 +158,7 @@ def print_script_execution_summary( if extra_sections is not None: extras |= extra_sections super().print_script_execution_summary(extra_sections=extras) - # [end customizing-the-summary] + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: self.parse_args(argv) From fd976faf22cb0f5d3c478f37513894cb97525832 Mon Sep 17 00:00:00 2001 From: lavafreak Date: Thu, 4 Jun 2026 14:40:41 -0600 Subject: [PATCH 3/3] style: apply pre-commit formatting --- example/ex_1_removing_the_retry_arguments.py | 1 + example/ex_2_running_certain_stages_by_default.py | 1 + example/ex_3_adding_arguments.py | 3 +++ example/ex_4_customizing_stage_behavior.py | 1 + example/ex_5_customizing_individual_stages.py | 1 + example/ex_6_creating_retryable_stages.py | 3 +++ example/ex_7_customizing_the_summary.py | 1 + 7 files changed, 11 insertions(+) diff --git a/example/ex_1_removing_the_retry_arguments.py b/example/ex_1_removing_the_retry_arguments.py index ad336a1..123cc6a 100755 --- a/example/ex_1_removing_the_retry_arguments.py +++ b/example/ex_1_removing_the_retry_arguments.py @@ -38,6 +38,7 @@ def parser(self) -> ArgumentParser: self.goodbye_retry_delay_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] 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: diff --git a/example/ex_2_running_certain_stages_by_default.py b/example/ex_2_running_certain_stages_by_default.py index 6c66ff1..51f2095 100755 --- a/example/ex_2_running_certain_stages_by_default.py +++ b/example/ex_2_running_certain_stages_by_default.py @@ -41,6 +41,7 @@ def parser(self) -> ArgumentParser: self.goodbye_retry_timeout_arg.help = argparse.SUPPRESS # type: ignore[attr-defined] my_parser.set_defaults(stage=list(self.stages)) return my_parser + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: diff --git a/example/ex_3_adding_arguments.py b/example/ex_3_adding_arguments.py index 2fbf586..b74ad6d 100755 --- a/example/ex_3_adding_arguments.py +++ b/example/ex_3_adding_arguments.py @@ -29,6 +29,7 @@ def say_goodbye(self) -> None: self.console.log( "Some flag was " + ("not " if not self.flag else "") + "set!" ) + # [end include-in-docs-examples-stage-usage] # [start include-in-docs-examples-parser] @@ -58,6 +59,7 @@ def parser(self) -> ArgumentParser: help="Some flag your users can toggle on if they like.", ) return my_parser + # [end include-in-docs-examples-parser] # [start include-in-docs-examples-parse-args] @@ -73,6 +75,7 @@ def parse_args(self, argv: list[str]) -> None: # arguments, whether you save them as instance attributes or # not. self.args.some_file = self.args.some_file.resolve() + # [end include-in-docs-examples-parse-args] def main(self, argv: list[str]) -> None: diff --git a/example/ex_4_customizing_stage_behavior.py b/example/ex_4_customizing_stage_behavior.py index 9a9ab90..ba25aa6 100755 --- a/example/ex_4_customizing_stage_behavior.py +++ b/example/ex_4_customizing_stage_behavior.py @@ -92,6 +92,7 @@ def _run_post_stage_actions(self) -> None: self.console.log( "Checking to make sure all is well after running the stage..." ) + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: diff --git a/example/ex_5_customizing_individual_stages.py b/example/ex_5_customizing_individual_stages.py index df30d95..c6c1c89 100755 --- a/example/ex_5_customizing_individual_stages.py +++ b/example/ex_5_customizing_individual_stages.py @@ -111,6 +111,7 @@ def _end_stage_goodbye(self) -> None: # You can also override things completely by omitting any `self` # 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: diff --git a/example/ex_6_creating_retryable_stages.py b/example/ex_6_creating_retryable_stages.py index 3eb0fb2..acb0ea0 100755 --- a/example/ex_6_creating_retryable_stages.py +++ b/example/ex_6_creating_retryable_stages.py @@ -35,6 +35,7 @@ def __init__( print_commands=print_commands, ) self.num_times_flaky_run = 0 + # [end include-in-docs-examples-init] @StagedScript.stage("hello", "Greeting the user") @@ -53,6 +54,7 @@ def try_error_prone_operation(self) -> None: raise RetryStage 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") @@ -91,6 +93,7 @@ def parser(self) -> ArgumentParser: help="Some flag your users can toggle on if they like.", ) return my_parser + # [end include-in-docs-examples-parser] def parse_args(self, argv: list[str]) -> None: diff --git a/example/ex_7_customizing_the_summary.py b/example/ex_7_customizing_the_summary.py index 9fd958c..9a7c6ac 100755 --- a/example/ex_7_customizing_the_summary.py +++ b/example/ex_7_customizing_the_summary.py @@ -158,6 +158,7 @@ def print_script_execution_summary( if extra_sections is not None: extras |= extra_sections super().print_script_execution_summary(extra_sections=extras) + # [end include-in-docs-examples] def main(self, argv: list[str]) -> None: