Merge pull request #21 from sandialabs/fill-out-docs

Create documentation and examples

Author: jmgate

.bandit

@@ -0,0 +1,2 @@
+[bandit]
+skips = B603

CONTRIBUTING.md

@@ -48,12 +48,12 @@ Before you begin hacking on `staged-script`, you'll need to do a few things:
    ```
 3. **Run the Examples:**  Ensure you can run all the examples with
    ```bash
-   cd /path/to/reverse_argparse/example
+   cd /path/to/staged-script/example
    ./run-all.bash
    ```
 4. **Build the Documentation:**  Ensure you can build the documentation with
    ```bash
-   cd /path/to/reverse_argparse/doc
+   cd /path/to/staged-script/doc
    ./make-html.bash
    ```
 

README.md

@@ -47,8 +47,12 @@ python3 -m pip install staged-script
 
 Once installed, you can simply
 ```python
+import sys
+from typing import List
+
 from staged_script import StagedScript
 
+
 class MyScript(StagedScript):
 
     @StagedScript.stage("hello", "Greeting the user")
@@ -59,14 +63,15 @@ class MyScript(StagedScript):
     def say_goodbye(self) -> None:
         self.run("echo 'Goodbye World'", shell=True)
 
-    def main(self, argv: list[str]) -> None:
+    def main(self, argv: List[str]) -> None:
         self.parse_args(argv)
         try:
             self.say_hello()
             self.say_goodbye()
         finally:
             self.print_script_execution_summary()
 
+
 if __name__ == "__main__":
     my_script = MyScript({"hello", "goodbye"})
     my_script.main(sys.argv[1:])
@@ -102,6 +107,10 @@ See [LICENSE.md](LICENSE.md).
 ## Credits
 
 Special thanks to [the GMS project][gms] for investing in the development of
-this package.
+this package.  Aspects of this functionality were inspired by the
+[SPiFI][spifi] Jenkins Pipeline plugin and the [ShellLogger][shelllogger]
+Python package.
 
 [gms]: https://github.com/SNL-GMS/GMS-PI25
+[spifi]: https://github.com/sandialabs/SPiFI
+[shelllogger]: https://github.com/sandialabs/shell-logger

doc/requirements.txt

@@ -4,4 +4,5 @@ sphinx
 sphinx-autodoc-typehints
 sphinx-copybutton
 sphinx-rtd-theme
+sphinxcontrib-mermaid
 sphinxcontrib-programoutput

doc/source/conf.py

@@ -31,6 +31,7 @@
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_rtd_theme",
+    "sphinxcontrib.mermaid",
     "sphinxcontrib.programoutput",
 ]
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}