Fix main exception handling

eudoxys · Oct 2, 2024 · 0bebd97 · 0bebd97
1 parent de2e840
commit 0bebd97
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 24 deletions.
diff --git a/docs/index.html b/docs/index.html
@@ -3,7 +3,7 @@
     <head>
         <title>Quickdocs</title>
         <meta name="expires" content="86400" />
-        <link rel="stylesheet" href="mystyles.css">
+        <link rel="stylesheet" href="quickdocs.css">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <link rel="stylesheet" href="https://www.w3schools.com/w3css/4/w3.css">
     </head>
@@ -74,11 +74,16 @@ <h2 class="w3-container">Text Formatting</h2>
 
 <h1 id="python" class="w3-container">Python Library</h1>
 
-<h2 class="w3-container"><code><b>CommandError</b>() &rightarrow; <i>None</i></code></h2>
+<h2 class="w3-container"><code><b>QuickdocsError</b>() &rightarrow; <i>None</i></code></h2>
 <p/>Error caused by an invalid or missing command line option
 
-<h2 class="w3-container"><code><b>main</b>(<b>argv</b>:<i>list</i>) &rightarrow; <i>None</i></code></h2>
+<h2 class="w3-container"><code><b>main</b>() &rightarrow; <i>None</i></code></h2>
 <p/>Main CLI
+<p/>    Runs the main <code>quickdocs</code> program. Generates the <code>docs/index.html</code> from
+    the <code>README.md</code> file and from the module created using the
+    <code>pyproject.toml</code> file.  If the <code>WITHCSS</code> is set to a file that exists, it
+    also copies that file to the <code>docs/</code> folder and references it in the HTML
+    file.
 <p/><h3 class="w3-container">Arguments</h3>
 <ul><li><code>argv (list[str])</code>:  argument list (default is sys.argv)</li>
 </li>
@@ -87,7 +92,18 @@ <h3 class="w3-container">Returns</h3>
 <ul><li><code>int</code>:  exit code</li>
 </li>
 </ul>
-<p/>    
+<h3 class="w3-container">Properties</h3>
+<ul><li><code>DEBUG (bool)</code>:  enable debugging traceback on exception</li>
+<li><code>WITHCSS (str)</code>:  enable copying CSS file to `docs/`</li>
+</li>
+</ul>
+<h3 class="w3-container">Exceptions</h3>
+<ul><li><code>Exception</code>:  exceptions are only raised if `DEBUG` is `True`.</li>
+<li><code>FileNotFoundError</code>:  exception raised when an input file is not found.</li>
+<li><code>QuickdocsError</code>:  exception raised when an invalid command argument is encountered.</li>
+</li>
+</ul>
+
 <h2 class="w3-container">Python Constants</h2><p/><code>E_ERROR = 1</code><p/><code>E_OK = 0</code>
 <h1 id="package" class="w3-container">Package Metadata</h1>
 <p/><table class="w3-container">

diff --git a/quickdocs.py b/quickdocs.py
@@ -92,21 +92,13 @@
 import datetime as dt
 import shutil
 
-class CommandError(Exception):
+class QuickdocsError(Exception):
     """Error caused by an invalid or missing command line option"""
 
 E_OK = 0
 E_ERROR = 1
 
-def main(argv:list[str]=sys.argv):
-    """Main CLI
-
-    Arguments:
-        argv (list[str]): argument list (default is sys.argv)
-
-    Returns:
-        int: exit code
-    """
+def _main(argv:list[str]=sys.argv):
 
     main.DEBUG = False
     withcss = False
@@ -126,7 +118,7 @@ def main(argv:list[str]=sys.argv):
         elif key == "--withcss":
             withcss = value if value else "quickdocs.css"
         elif arg != "-":
-            raise CommandError(f"invalid option '{arg}'")
+            raise QuickdocsError(f"invalid option '{arg}'")
 
     with open("pyproject.toml","rb") as fh:
         package = tomllib.load(fh)["project"]
@@ -151,6 +143,9 @@ def main(argv:list[str]=sys.argv):
 
     os.makedirs("docs",exist_ok=True)
 
+    if withcss:
+        shutil.copy(withcss,"docs/quickdocs.css")
+
     with open("docs/index.html","w",encoding="utf-8") as html:
 
         def write_html(text,md=True,nl=False):
@@ -335,7 +330,7 @@ def get_mode():
                         write_html(f" &rightarrow; *{c}*")
                     except KeyError:
                         write_html(" &rightarrow; *None*")
-                    write_html("</code></h2>\n")
+                    write_html("</code></h2>\n<p/>")
 
                     for line in value.__doc__.split("\n"):
                         if len(line) == 0:
@@ -353,7 +348,7 @@ def get_mode():
                                 write_html(f"<li>{part[0]}</li>\n",md=False)
                         else:
                             set_mode(None)
-                            write_html(f"<p/>{line}\n")
+                            write_html(f"{line}\n")
                 else:
                     print(f"WARNING: function '{name}' has no __doc__")
             set_mode(None)
@@ -384,18 +379,42 @@ def get_mode():
         write_html("""</body>
             </html>""",nl=True)
 
-    if withcss:
-        shutil.copy(withcss,"docs/quickdocs.css")
-
     return E_OK
 
-if __name__ == "__main__":
+def main(argv=sys.argv):
+    """Main CLI
+
+    Runs the main `quickdocs` program. Generates the `docs/index.html` from
+    the `README.md` file and from the module created using the
+    `pyproject.toml` file.  If the `WITHCSS` is set to a file that exists, it
+    also copies that file to the `docs/` folder and references it in the HTML
+    file.
+
+    Arguments:
+        argv (list[str]): argument list (default is sys.argv)
+
+    Returns:
+        int: exit code
+
+    Properties:
+        DEBUG (bool): enable debugging traceback on exception
+        WITHCSS (str): enable copying CSS file to `docs/`
+
+    Exceptions:
+        Exception: exceptions are only raised if `DEBUG` is `True`.
+        FileNotFoundError: exception raised when an input file is not found.
+        QuickdocsError: exception raised when an invalid command argument is encountered.
+    """
     try:
-        exit(main())
+        rc = _main()
     except Exception:
         e_type,e_value,e_trace = sys.exc_info()
-        print(f"ERROR [{os.path.basename(sys.argv[0])[:-2] + e_type.__name__}]:" +
+        print(f"ERROR [{os.path.basename(sys.argv[0])} {e_type.__name__}]:" +
             f" {e_value}",file=sys.stderr,flush=True)
         if main.DEBUG:
             raise
-        exit(E_ERROR)
+        rc = E_ERROR
+    return rc
+
+if __name__ == "__main__":
+    exit(main())