aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorElena ``of Valhalla'' Grandi <valhalla@trueelena.org>2022-03-12 20:20:15 +0100
committerElena ``of Valhalla'' Grandi <valhalla@trueelena.org>2022-03-12 20:20:15 +0100
commit049f21cfe779dbcd795d04917dff4ec3034a1546 (patch)
treed2a6de4168709cb01324a37619d4c350128ec6ee /docs
parent11da28ef036aeb872f1e5c509b43ae6b9bb64da2 (diff)
Beginning of a tutorial in the docs
Diffstat (limited to 'docs')
-rwxr-xr-xdocs/source/examples/greeter.py40
-rw-r--r--docs/source/index.rst1
-rw-r--r--docs/source/tutorial.rst98
3 files changed, 139 insertions, 0 deletions
diff --git a/docs/source/examples/greeter.py b/docs/source/examples/greeter.py
new file mode 100755
index 0000000..5a978f4
--- /dev/null
+++ b/docs/source/examples/greeter.py
@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+import hazwaz
+
+
+class World(hazwaz.Command):
+ """
+ Greet the whole world.
+ """
+
+ def main(self):
+ print("Hello world!")
+
+
+class Individual(hazwaz.Command):
+ """
+ Greet an individual.
+ """
+
+ def add_arguments(self, parser):
+ parser.add_argument(
+ "gretee",
+ help="The person to be greeted",
+ )
+
+ def main(self):
+ print("Hello {}".format(self.args.gretee))
+
+
+class Greet(hazwaz.MainCommand):
+ """
+ Greet people in different ways.
+ """
+ commands = (
+ World(),
+ Individual(),
+ )
+
+
+if __name__ == "__main__":
+ Greet().run()
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 2b5c1f0..3440917 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,6 +15,7 @@ Contents
:maxdepth: 2
:caption: Contents:
+ tutorial
reference/modules
Indices and tables
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
new file mode 100644
index 0000000..eb077fd
--- /dev/null
+++ b/docs/source/tutorial.rst
@@ -0,0 +1,98 @@
+**********
+ Tutorial
+**********
+
+In this tutorial, we'll write a command that greets people in different
+ways.
+
+We start with the scaffolding (shebang, imports, …) and with a class
+that subclasses :py:class:`MainCommand <hazwaz.command.MainCommand>`, is
+instantiated and its method :py:meth:`run
+<hazwaz.command.MainCommand.run>` is called::
+
+
+ #!/usr/bin/env python3
+ import hazwaz
+
+
+ class Greet(hazwaz.MainCommand):
+ """
+ Greet people in different ways.
+ """
+
+
+ if __name__ == "__main__":
+ Greet().run()
+
+Save this in a file called greeter.py and run it, and it will print an
+help message where you can already see a couple of options,
+``--verbose`` and ``debug``, as well as the first line of the docstring
+used as the usage.
+
+Now we add our first subcommand: we write a new class, subclassing
+:py:class:`Command <hazwaz.command.Command>` and writing some code in
+its :py:meth:`main <hazwaz.command.Command.main>` method::
+
+ class World(hazwaz.Command):
+ """
+ Greet the whole world.
+ """
+
+ def main(self):
+ print("Hello world!")
+
+And we add an instance to the tuple of subcommands in our MainCommand::
+
+ class Greet(hazwaz.MainCommand):
+ """
+ Greet people in different ways.
+ """
+ commands = (
+ World(),
+ )
+
+now if we run the program as ``./greeter.py`` we see that there is a
+possible choice for a positional argument, ``world``, and if we run
+``./greeter.py world`` we get, as expected, a greeting ``Hello world!``.
+
+With ``./greeter.py world --help`` we can see the help message for this
+subcommand, and notice that the first line in the docstring has again
+been used as the usage notes.
+
+Of course, a subcommand can also have options: we write a second
+subclass of :py:class:`Command <hazwaz.command.Command>` and this time
+we add some argparser option in the :py:meth:`add_arguments
+<hazwaz.command.Command.add_arguments>` method::
+
+ class Individual(hazwaz.Command):
+ """
+ Greet an individual.
+ """
+
+ def add_arguments(self, parser):
+ parser.add_argument(
+ "gretee",
+ help="The person to be greeted",
+ )
+
+ def main(self):
+ print("Hello {}".format(self.args.gretee))
+
+And again we add it to the tuple of subcommands::
+
+ class Greet(hazwaz.MainCommand):
+ """
+ Greet people in different ways.
+ """
+ commands = (
+ World(),
+ Individual(),
+ )
+
+You can then run the program as ``./greeter.py individual Bob`` to see
+the new greeting.
+
+:py:meth:`add_arguments <hazwaz.command.Command.add_arguments>` requires
+an :py:class:`argparse.ArgumentParser` as its second parameter, and
+uses it to add arbitrary arguments, giving access to all argparse
+features.