Add validation matrix for linux, macos, windows over python versions (#4

)

* Update validate-main.yaml
* Update qdox.py
* Update index.html
* Update pyproject.toml

.github/workflows/validate-main.yaml

@@ -7,23 +7,91 @@ on:
     branches: [main]
 
 jobs:
-  validate:
-    runs-on: ubuntu-latest
+
+  validate-matrix-linux:
+    strategy:
+      matrix:
+        os-version: [ubuntu-22.04, ubuntu-24.04]
+        python-version: [3.11, 3.12]
+
+    runs-on: ${{ matrix.os-version }}
+    continue-on-error: true
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Lint
+      run: |
+        python3 -m venv .venv
+        source .venv/bin/activate
+        python3 -m pip install pip --upgrade pylint
+        pylint qdox.py
+
+    - name: Validate
+      run: |
+        python3 -m pip install .
+        mv docs/index.html docs/validate.html
+        python3 -m qdox --withcss
+        diff docs/index.html docs/validate.html || (echo '***ERROR***: Did you forget to run `make` before pushing your latest changes?' >/dev/stderr && false)
+
+  validate-matrix-macos:
+    strategy:
+      matrix:
+        os-version: [macos-13, macos-14, macos-15]
+        python-version: [3.11, 3.12]
+
+    runs-on: ${{ matrix.os-version }}
+    continue-on-error: true
 
     steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-python@v5
       with:
-        python-version: '3.11'
+        python-version: ${{ matrix.python-version }}
 
     - name: Lint
       run: |
-        python3 -m pip install --user pip --upgrade pylint
+        python3 -m venv .venv
+        source .venv/bin/activate
+        python3 -m pip install pip --upgrade pylint
         pylint qdox.py
 
     - name: Validate
       run: |
         python3 -m pip install .
         mv docs/index.html docs/validate.html
         python3 -m qdox --withcss
-        diff docs/index.html docs/validate.html || (echo '***ERROR***: Did you forget to run `make` before pushing your latest changes?' >/dev/stderr;false)
+        diff docs/index.html docs/validate.html || (echo '***ERROR***: Did you forget to run `make` before pushing your latest changes?' >/dev/stderr && false)
+
+  validate-matrix-windows:
+    strategy:
+      matrix:
+        os-version: [windows-2019, windows-2022]
+        python-version: [3.11, 3.12]
+
+    runs-on: ${{ matrix.os-version }}
+    continue-on-error: true
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Lint
+      run: |
+        python3 -m venv .venv
+        . .venv/scripts/activate
+        python3 -m pip install pip --upgrade pylint
+        pylint qdox.py
+
+    - name: Validate
+      run: |
+        python3 -m pip install .
+        mv docs/index.html docs/validate.html
+        python3 -m qdox --withcss
+        diff docs/index.html docs/validate.html || (echo '***ERROR***: Did you forget to run `make` before pushing your latest changes?' >/dev/stderr && false)
+

docs/index.html

@@ -28,7 +28,7 @@
     <h1 id="main" class="w3-container">Command Line</h1>
 
     <p/>
-Generate docs/index.html from module and README.md
+Generate docs/index.html from module contents and metadata
 <p/>Syntax: <code>qdox [OPTION ...]</code><p/>
 <h2 class="w3-container">Options</h2>
 <p/><ul><li>
@@ -40,9 +40,9 @@ <h2 class="w3-container">Options</h2>
 
 <h2 class="w3-container">Description</h2>
 <p/>  The <code>qdox</code> command generates the documentation for a simple Python
-  project. The formatting is meants to use simple text layout as the input so
-  that the input can be used for both Python <code>help()</code> and the documentation
-  pages.
+  project. The formatting is designed to use simple text layout as the input 
+  so that the same documentation source can be used for both Python <code>help()</code> 
+  output and the documentation pages.
 <p/>  The command loads the module specified in the <code>pyproject.toml</code> file and
   outputs the <code>__doc__</code> property of the module as the command line
   documentation. It then outputs the python functions and constants,
@@ -78,7 +78,8 @@ <h2 class="w3-container">Text Formatting</h2>
 <code><code>!!text!!</code></code>:  <font class="highlight">Highlight</font> text</li><li>
 <code><code>~~text~~</code></code>:  <strike>strikeout</strike> text</li><li>
 <code><code>__text__</code></code>:  <u>underline</u> text</li><li>
-<code><code>^word</code></code>:  <sup>superscript</sup> word (ends at space)</li><li>
+<code><code>^word</code></code>:  <sup>superscript</sup> word (ends at space)<pre>
+</pre></li><li>
 <code><code>_word</code></code>:  <sub>subscript</sub> word (ends at space)</li><li>
 <code>`text`</code>:  <code>code</code> text</li><li>
 <code><code>protocol</code>: //url/</code>: <a href="protocol://url/" target="_tab">protocol://url/</a> formatting with active link</li></li>
@@ -120,7 +121,7 @@ <h2 class="w3-container">Python Constants</h2><p/><code>E_ERROR = 1</code><p/><c
 <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>
-<tr><th><nobr>Version</nobr></th><td>:</td><td>0.0.0a1</td></tr>
+<tr><th><nobr>Version</nobr></th><td>:</td><td>0.0.0a2</td></tr>
 <tr><th><nobr>Description</nobr></th><td>:</td><td>Generate quick documentation for a Python project on GitHub</td></tr>
 <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>

pyproject.toml

@@ -7,7 +7,7 @@ py-modules = []
 
 [project]
 name = "qdox"
-version = "0.0.0a1"
+version = "0.0.0a2"
 description = "Generate quick documentation for a Python project on GitHub"
 authors = [
     {name = "David P. Chassin <[email protected]>"},

qdox.py

@@ -1,4 +1,4 @@
-"""Generate docs/index.html from module and README.md
+"""Generate docs/index.html from module contents and metadata
 
 Syntax: qdox [OPTION ...]
 
@@ -85,8 +85,11 @@
     * `!!text!!`: !!Highlight!! text
 
     * `~~text~~`: ~~strikeout~~ text
+
     * `__text__`: __underline__ text
+
     * `^word`: ^superscript word (ends at space)
+    
     * `_word`: _subscript word (ends at space)
 
     * ``text``: `code` text
@@ -115,10 +118,20 @@ def _get_json(*args,**kwargs):
         with requests.get(*args,**kwargs,timeout=60) as res:
             if res.status_code == 200:
                 return json.loads(res.text)
-            return {"error": "request failed", "message": f"StatusCode:{res.status_code}"}
+            qargs = [repr(x) for x in args] + \
+                [f"{str(x)}={repr(y)}" for x,y in kwargs.items()]
+            return {
+                "error": "request failed", 
+                "message": f"requests.get({','.join(qargs)}) -> StatusCode={res.status_code}",
+                }
     except:
         e_type, e_name, _ = sys.exc_info()
-        return {"error": "request failed", "message": f"{e_type.__name__}={e_name}"}
+        qargs = [repr(x) for x in args] + \
+            [f"{str(x)}={repr(y)}" for x,y in kwargs.items()]
+        return {
+            "error": "request failed", 
+            "message": f"requests.get({','.join(qargs)}) -> {e_type.__name__}={e_name}",
+            }
 
 class QdoxError(Exception):
     """Error caused by an invalid or missing command line option"""
@@ -174,6 +187,8 @@ def _main(argv:list[str]=sys.argv) -> int:
 
     org = homepage.split("/")[-2]
     github_data = _get_json(f"https://api.github.com/users/{org}")
+    if "error" in github_data:
+        raise QdoxError(github_data["message"])
 
     os.makedirs("docs",exist_ok=True)