Improved the documentation (resectioning, rephrasing, new examples)

docs/examples/demo.md

@@ -6,61 +6,35 @@ Very basic script demonstrating the demonstration feature, adding an option to s
 
     If `__examples__` is not defined or is en empty list, the `--demo` will simply not be available, even if `add_demo` is `True` in the `initialize` function.
 
-### Creation
-
-```sh
-$ tinyscript-new script --name demo
-$ gedit demo.py
-
-```
-
 ### Code
 
-```python hl_lines="6 11"
-#!/usr/bin/env python
-# -*- coding: UTF-8 -*-
+```python hl_lines="3 7"
 from tinyscript import *
 
-
 __examples__ = ["", "--test"]
 
-
 if __name__ == '__main__':
     parser.add_argument("--test", action="store_true", help="test argument")
-    initialize(globals(), add_demo=True)
+    initialize(add_demo=True)
     logger.success("First example" if not args.test else "Second example")
 ```
 
 ### Help
 
-```sh hl_lines="10"
+```sh
 $ python demo.py -h
-usage: python demo.py [--test] [--demo] [-h] [-v]
-
-Demo
-
-optional arguments:
-  --test         test argument (default: False)
-
-extra arguments:
-  --demo         demonstrate a random example
-  -h, --help     show this help message and exit
-  -v, --verbose  verbose mode (default: False)
-
-Usage examples:
-  python demo.py 
-  python demo.py --test
+usage: python demo.py [--test] [--demo] [-h] [--help] [-v]
 
 ```
 
 ### Execution
 
-```sh hl_lines="1 2"
+```sh hl_lines="1"
 $ python demo.py --demo
 12:34:56 [SUCCESS] First example
 ```
 
-```sh hl_lines="1 2"
+```sh hl_lines="1"
 $ python demo.py --demo
 12:34:56 [SUCCESS] Second example
 ```

docs/examples/metadata.md

@@ -2,58 +2,47 @@
 
 Very basic script demonstrating how to include metadata and how it is rendered in the help message.
 
-### Creation
-
-```sh
-$ tinyscript-new script --name metadata
-$ gedit metadata.py
-
-```
-
 ### Code
 
-```python hl_lines="6 7 8 9 10"
-#!/usr/bin/env python
-# -*- coding: UTF-8 -*-
+```python hl_lines="3 4 5 6 7"
 from tinyscript import *
 
-
 __author__    = "John Doe"
 __email__     = "john.doe@example.com"
 __version__   = "1.0"
 __examples__  = [""]
 __doc__       = "This script prints a simple 'Hello world !'"
 
-
 if __name__ == '__main__':
-    initialize(globals())
+    initialize()
     logger.success("Hello world !")
 ```
 
 ### Help
 
 ```sh hl_lines="5 7"
 $ python metadata.py -h
-usage: metadata [-h] [-v]
-
-Metadata v1.0
-Author: John Doe (john.doe@example.com)
+Tool 1.0
+Author   : John Doe (john.doe@example.com)
 
 This script prints a simple 'Hello world !'
 
+usage: python metadata.py [-h] [--help] [-v]
+
 extra arguments:
-  -h, --help     show this help message and exit
+  -h             show usage message and exit
+  --help         show this help message and exit
   -v, --verbose  verbose mode (default: False)
 
-Usage examples:
-  python metadata.py 
+Usage example:
+  python metadata.py
 
 ```
 
 ### Execution
 
 ```sh
-$ python metadata.py 
+$ python metadata.py
 12:34:56 [SUCCESS] Hello world !
 
 ```

docs/examples/multi-level-debug.md

@@ -2,24 +2,13 @@
 
 Very basic script demonstrating the multi-level debug mode.
 
-### Creation
-
-```sh
-$ tinyscript-new script --name multi-level-debug
-$ gedit multi-level-debug.py
-
-```
-
 ### Code
 
-```python hl_lines="7"
-#!/usr/bin/env python
-# -*- coding: UTF-8 -*-
+```python hl_lines="4"
 from tinyscript import *
 
-
 if __name__ == '__main__':
-    initialize(globals(), multi_level_debug=True)
+    initialize(multi_level_debug=True)
     logger.critical("This is always displayed")
     logger.error("This is always displayed")
     logger.warning("This is displayed with -v")
@@ -30,15 +19,16 @@ if __name__ == '__main__':
 ### Help
 
 ```sh hl_lines="8 9"
-$ python multi-level-debug.py -h
-usage: python multi-level-debug.py [-h] [-v]
+$ python multi-level-debug.py --help
+Tool 
 
-MultiLevelDebug
+usage: python multi-level-debug.py [-h] [--help] [-v]
 
 extra arguments:
-  -h, --help  show this help message and exit
-  -v          verbose level (default: 0)
-               NB: -vvv is the highest verbosity level
+  -h      show usage message and exit
+  --help  show this help message and exit
+  -v      verbose level (default: 0)
+           NB: -vvv is the highest verbosity level
 
 ```
 

docs/examples/multi-level-help.md

@@ -2,80 +2,56 @@
 
 Very basic script demonstrating the multi-level help messages.
 
-### Creation
-
-```sh
-$ tinyscript-new script --name multi-level-help
-$ gedit multi-level-help.py
-
-```
-
 ### Code
 
 ```python hl_lines="7 8 9 10"
-#!/usr/bin/env python
-# -*- coding: UTF-8 -*-
 from tinyscript import *
 
-
 __doc__ = "Main description"
 __details__ = [
     "First level of details",
     "Second level of details",
 ]
 
-
 if __name__ == '__main__':
-    initialize(globals())
+    initialize()
 ```
 
 ### Help
 
-```sh hl_lines="1 9 10"
+```sh hl_lines="1 4"
 $ python multi-level-help.py -h
-usage: python multi-level-help.py [-h] [-v]
-
-MultiLevelHelp
+Tool
 
 Main description
 
+usage: ./tool.py [-h] [-v]
+
 extra arguments:
   -h             show extended help message and exit (default: 0)
                   NB: -hhh is the highest help detail level
   -v, --verbose  verbose mode (default: False)
 
 ```
 
-```sh hl_lines="1 13"
+```sh hl_lines="1 7"
 $ python multi-level-help.py -hh
-usage: python multi-level-help.py [-h] [-v]
-
-MultiLevelHelp
-
-Main description
-
-extra arguments:
-  -h             show extended help message and exit (default: 0)
-                  NB: -hhh is the highest help detail level
+Tool
+[...]
   -v, --verbose  verbose mode (default: False)
 
+
 First level of details
 
 ```
 
-```sh hl_lines="1 13 15"
+```sh hl_lines="1 7 9"
 $ python multi-level-help.py -hh
-usage: python multi-level-help.py [-h] [-v]
-
-MultiLevelHelp
-
-Main description
-
-extra arguments:
-  -h             show extended help message and exit (default: 0)
-                  NB: -hhh is the highest help detail level
+Tool
+[...]
   -v, --verbose  verbose mode (default: False)
 
+
 First level of details
 
 Second level of details

docs/examples/simple-script.md

@@ -2,14 +2,6 @@
 
 Very basic script, with no particular feature used.
 
-### Creation
-
-```sh
-$ tinyscript-new script --name simple-script
-$ gedit simple-script.py
-
-```
-
 ### Code
 
 ```python
@@ -20,23 +12,24 @@ from tinyscript import *
 
 if __name__ == '__main__':
     parser.add_argument("string", help="string to be displayed")
-    initialize(globals())
+    initialize()
     logger.info(args.string)
 ```
 
 ### Help
 
 ```sh
 $ python simple-script.py -h
-usage: simple-script [-h] [-v] string
-
 SimpleScript
 
+usage: simple-script [-h] [--help] [-v] string
+
 positional arguments:
   string         string to be displayed
 
 extra arguments:
-  -h, --help     show this help message and exit
+  -h             show usage message and exit
+  --help         show this help message and exit
   -v, --verbose  verbose mode (default: False)
 
 ```

docs/examples/simple-tool.md

@@ -2,14 +2,6 @@
 
 Very basic tool, using the demonstration feature when no argument is given. It also redefines a constant for tuning the logging.
 
-### Creation
-
-```sh
-$ tinyscript-new tool --name simple-tool
-$ gedit simple-tool.py
-
-```
-
 ### Code
 
 ```python
@@ -37,32 +29,32 @@ def hello(message, critical=False):
 # ---------------------- MAIN SECTION -----------------------
 if __name__ == '__main__':
     parser.add_argument("message", help="message to be displayed")
-    parser.add_argument("--critical", action="store_true",
-                        help="critical message")
-    initialize(globals(), noargs_action="demo")
+    parser.add_argument("--critical", action="store_true", help="critical message")
+    initialize(noargs_action="demo")
     hello(args.message, args.critical)
 ```
 
 ### Help
 
 ```sh
 $ python simple-tool.py -h
-usage: simple-tool [-h] [-v] [--critical] message
-
 SimpleTool v1.0
 Author: John Doe
 Reference: John's Blog (http://blogsite.com/john/)
 
 This tool is a simple example from the Tinyscript project.
 
+usage: python simple-tool.py [--critical] [-h] [--help] [-v] message
+
 positional arguments:
   message        message to be displayed
 
 optional arguments:
   --critical     critical message (default: False)
 
 extra arguments:
-  -h, --help     show this help message and exit
+  -h             show usage message and exit
+  --help         show this help message and exit
   -v, --verbose  verbose mode (default: False)
 
 Usage examples: