diff --git a/doc/source/examples.rst b/doc/source/examples.rst index 3ba1064..8ec1793 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 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`` diff --git a/doc/source/index.rst b/doc/source/index.rst index b362e0e..d40c99e 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 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 1f1c64e..4f6e5c5 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 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] diff --git a/example/ex_1_removing_the_retry_arguments.py b/example/ex_1_removing_the_retry_arguments.py index dc8a167..123cc6a 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 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: diff --git a/example/ex_2_running_certain_stages_by_default.py b/example/ex_2_running_certain_stages_by_default.py index 683674e..51f2095 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 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: diff --git a/example/ex_3_adding_arguments.py b/example/ex_3_adding_arguments.py index 282b931..b74ad6d 100755 --- a/example/ex_3_adding_arguments.py +++ b/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: diff --git a/example/ex_4_customizing_stage_behavior.py b/example/ex_4_customizing_stage_behavior.py index f6e507c..ba25aa6 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 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: diff --git a/example/ex_5_customizing_individual_stages.py b/example/ex_5_customizing_individual_stages.py index 7cf63b8..c6c1c89 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 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: diff --git a/example/ex_6_creating_retryable_stages.py b/example/ex_6_creating_retryable_stages.py index 5b79bb0..acb0ea0 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 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,6 +55,8 @@ 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) @@ -58,6 +64,7 @@ def say_goodbye(self) -> None: "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) diff --git a/example/ex_7_customizing_the_summary.py b/example/ex_7_customizing_the_summary.py index 2a21d5c..9a7c6ac 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 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: