Refactored package for general use

Makefile

@@ -3,11 +3,15 @@
 # You must run this after updating the code to ensure the documentation is updated as well
 #
 
-docs/index.html: qdox.py qdox.css Makefile pyproject.toml .venv/bin/activate
+VENV=".venv/bin/activate"
+
+docs/index.html: src/qdox/main.py src/qdox/__init__.py src/qdox/qdox.css Makefile pyproject.toml $(VENV)
 	@echo Updating $@...
-	@(source .venv/bin/activate; pylint qdox.py || true)
-	@(source .venv/bin/activate; python3 -m qdox --withcss)
+	(source .venv/bin/activate; pylint $< || true)
+	(source .venv/bin/activate; python3 -m pip install .)
+	(source .venv/bin/activate; qdox --withcss --debug)
 
-.venv/bin/activate:
-	@test -d .venv || python3 -m venv .venv
-	@(source .venv/bin/activate; python3 -m pip install pip --upgrade -r requirements.txt .)
+$(VENV):
+	@echo Creating $@...
+	test -d .venv || python3 -m venv `echo $@ | cut -d/ -f1`
+	(source $@; python3 -m pip install pip --upgrade -r requirements.txt .)

docs/index.html

@@ -35,6 +35,7 @@ <h2 class="w3-container">Options</h2>
 <code>-</code>:  run with no options</li><li>
 <code>--debug</code>:  Enable debugging traceback on exceptions</li><li>
 <code>-h|--help|help</code>:  Display this help information</li><li>
+<code>--tomlfile=TOMFILE</code>:  Use TOMFILE instead of "pyproject.toml"</li><li>
 <code>--withcss[=CSSFILE]</code>:  Copy the CSS file to <code>docs/</code> (default is <code>qdox.css</code>)</li></li>
 </ul>
 
@@ -87,37 +88,6 @@ <h2 class="w3-container">Text Formatting</h2>
 
 <h1 id="python" class="w3-container">Python Library</h1>
 
-<h2 class="w3-container"><code><b>QdoxError</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>int</i></code></h2>
-<p/>Main CLI
-<p/>    Runs the main <code>qdox</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>
-</ul>
-<h3 class="w3-container">Returns</h3>
-<ul><li><code>int</code>:  exit code</li>
-</li>
-</ul>
-<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 <code>docs/</code></li>
-</li>
-</ul>
-<h3 class="w3-container">Exceptions</h3>
-<ul><li><code>Exception</code>:  exceptions are only raised if <code>DEBUG</code> is <code>True</code>.</li>
-<li><code>FileNotFoundError</code>:  exception raised when an input file is not found.</li>
-<li><code>QdoxError</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">
 <tr><th><nobr>Name</nobr></th><td>:</td><td>qdox</td></tr>
@@ -126,7 +96,7 @@ <h1 id="package" class="w3-container">Package Metadata</h1>
 <tr><th><nobr>Authors</nobr></th><td>:</td><td>David P. Chassin <dpchassin@gmail.com></td></tr>
 <tr><th><nobr>Maintainers</nobr></th><td>:</td><td>David P. Chassin <dpchassin@gmail.com></td></tr>
 <tr><th><nobr>Requires-Python</nobr></th><td>:</td><td>>= 3.11</td></tr>
-<tr><th><nobr>Dependencies</nobr></th><td>:</td><td>requests</td></tr>
+<tr><th><nobr>Dependencies</nobr></th><td>:</td><td>requests<br/>tomli</td></tr>
 <tr><th><nobr>Keywords</nobr></th><td>:</td><td>github<br/>python<br/>documentation</td></tr>
 <tr><th><nobr>License</nobr></th><td>:</td><td>MIT License</td></tr>
 <tr><th><nobr>Classifiers</nobr></th><td>:</td><td>Development Status :: 3 - Alpha<br/>Intended Audience :: Developers<br/>License :: OSI Approved :: MIT License<br/>Programming Language :: Python :: 3 :: Only<br/>Topic :: Software Development :: Libraries</td></tr>

pyproject.toml

@@ -2,8 +2,11 @@
 requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
-[tool.setuptools]
-py-modules = []
+[tools.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+qdox = ["*.py","*.css"]
 
 [project]
 name = "qdox"
@@ -17,7 +20,7 @@ maintainers = [
     ]
 readme = "README.md"
 requires-python = ">= 3.11"
-dependencies = ["requests"]
+dependencies = ["requests","tomli"]
 keywords = ["github","python","documentation"]
 license = {text="MIT License"}
 classifiers = [
@@ -35,4 +38,4 @@ Repository = "https://github.com/eudoxys/qdox.git"
 Issues = "https://github.com/eudoxys/qdox/issues"
 
 [project.scripts]
-qdox = "qdox:main"
+qdox = "qdox.main:main"

requirements.txt

@@ -1,2 +1 @@
-requests
 pylint

src/qdox/__init__.py

@@ -0,0 +1,2 @@
+from qdox import main
+from qdox.main import __doc__

qdox.py → src/qdox/main.py

@@ -10,6 +10,8 @@
 
     * -h|--help|help: Display this help information
 
+    * --tomlfile=TOMFILE: Use TOMFILE instead of "pyproject.toml"
+
     * --withcss[=CSSFILE]: Copy the CSS file to `docs/` (default is `qdox.css`)
 
 Description:
@@ -139,29 +141,34 @@ class QdoxError(Exception):
 E_OK = 0
 E_ERROR = 1
 
-def _main(argv:list[str]=sys.argv) -> int:
+def _main(argv:list[str]) -> int:
 
     main.DEBUG = False
     withcss = False
+    tomlfile = "pyproject.toml"
 
-    if len(sys.argv) == 1:
+    if len(argv) == 0:
         print([x for x in __doc__.split("\n") if x.startswith("Syntax: ")][0])
         return 0
 
-    if sys.argv[1] in ["-h","--help","help"]:
+    if argv[0] in ["-h","--help","help"]:
         print(__doc__)
         return 1
 
-    for arg in argv[1:]:
+    for arg in argv:
         key,value = arg.split("=",1) if "=" in arg else (arg,None)
         if arg == "--debug":
             main.DEBUG = True
         elif key == "--withcss":
-            withcss = value if value else "qdox.css"
+            if not __spec__:
+                raise QdoxError("you must use --withcss=FILE when running in Python")
+            withcss = value if value else os.path.join(os.path.dirname(__spec__.origin),"qdox.css")
+        elif key == "--tomlfile":
+            tomlfile = value if value else tomlfile
         elif arg != "-":
             raise QdoxError(f"invalid option '{arg}'")
 
-    with open("pyproject.toml","rb") as fh:
+    with open(tomlfile,"rb") as fh:
         package = tomllib.load(fh)["project"]
         homepage = package["urls"]["Homepage"]
         for item,key in {"authors":"name","maintainers":"name"}.items():
@@ -271,7 +278,7 @@ def get_mode():
     <head>
         <title>{package_name}</title>
         <meta name="expires" content="86400" />
-        <link rel="stylesheet" href="{withcss if withcss else 'qdox.css'}">
+        <link rel="stylesheet" href="{os.path.basename(withcss) if withcss else 'qdox.css'}">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <link rel="stylesheet" href="https://www.w3schools.com/w3css/4/w3.css">
     </head>
@@ -431,7 +438,7 @@ def get_mode():
 
     return E_OK
 
-def main(argv:list[str]=sys.argv) -> int:
+def main(argv:list[str]=sys.argv[1:]) -> int:
     """Main CLI
 
     Runs the main `qdox` program. Generates the `docs/index.html` from
@@ -459,12 +466,12 @@ def main(argv:list[str]=sys.argv) -> int:
         rc = _main(argv)
     except Exception:
         e_type,e_value,_ = sys.exc_info()
-        print(f"ERROR [{os.path.basename(sys.argv[0])} {e_type.__name__}]:" +
+        print(f"ERROR [qdox/{os.path.basename(sys.argv[0])}:{e_type.__name__}]:" +
             f" {e_value}",file=sys.stderr,flush=True)
         if main.DEBUG:
             raise
         rc = E_ERROR
     return rc
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main(sys.argv[1:]))