Rename to qdox

eudoxys · Oct 2, 2024 · 0562ce9 · 0562ce9
1 parent c9402e9
commit 0562ce9
Show file tree

Hide file tree

Showing 7 changed files with 59 additions and 52 deletions.
diff --git a/Makefile b/Makefile
@@ -3,10 +3,10 @@
 # You must run this after updating the code to ensure the documentation is updated as well
 #
 
-docs/index.html: quickdocs.py quickdocs.css Makefile pyproject.toml .venv/bin/activate
+docs/index.html: qdox.py qdox.css Makefile pyproject.toml .venv/bin/activate
 	@echo Updating $@...
-	@(source .venv/bin/activate; pylint quickdocs.py || true)
-	@(source .venv/bin/activate; python3 -m quickdocs --withcss)
+	@(source .venv/bin/activate; pylint qdox.py || true)
+	@(source .venv/bin/activate; python3 -m qdox --withcss)
 
 .venv/bin/activate:
 	@test -d .venv || python3 -m venv .venv

diff --git a/README.md b/README.md
@@ -1,13 +1,13 @@
-[![Validate main](https://github.com/dchassin/quickdocs/actions/workflows/validate-main.yaml/badge.svg)](https://github.com/dchassin/quickdocs/actions/workflows/validate-main.yaml)
-[![pages-build-deployment](https://github.com/dchassin/quickdocs/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/dchassin/quickdocs/actions/workflows/pages/pages-build-deployment)
+[![Validate main](https://github.com/dchassin/qdox/actions/workflows/validate-main.yaml/badge.svg)](https://github.com/dchassin/qdox/actions/workflows/validate-main.yaml)
+[![pages-build-deployment](https://github.com/dchassin/qdox/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/dchassin/qdox/actions/workflows/pages/pages-build-deployment)
 
-# quickdocs
+# qdox
 
 Quick documentation generator.
 
 ## Documentation
 
-See http://www.chassin.org/quickdocs for full documentation.
+See http://www.chassin.org/qdox for full documentation.
 
 ## Updating
 

diff --git a/docs/index.html b/docs/index.html
@@ -1,9 +1,9 @@
 <!doctype html>
     <html>
     <head>
-        <title>Quickdocs</title>
+        <title>Qdox</title>
         <meta name="expires" content="86400" />
-        <link rel="stylesheet" href="quickdocs.css">
+        <link rel="stylesheet" href="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>
@@ -16,7 +16,7 @@
         <br/><a href="https://www.chassin.org/">David P. Chassin</a>
         <br/><a href="https://www.eudoxys.com/">Eudoxys Sciences LLC</a>
       </center>
-      <title class="w3-bar-item">Quickdocs</title>
+      <title class="w3-bar-item">qdox</title>
       <a href="#main" class="w3-bar-item w3-button">Command Line</a>
       <a href="#python" class="w3-bar-item w3-button">Python Library</a>
       <a href="#package" class="w3-bar-item w3-button">Package Metadata</a>
@@ -29,17 +29,17 @@ <h1 id="main" class="w3-container">Command Line</h1>
 
     <p/>
 Generate docs/index.html from module and README.md
-<p/>Syntax: <code>quickdocs [OPTION ...]</code><p/>
+<p/>Syntax: <code>qdox [OPTION ...]</code><p/>
 <h2 class="w3-container">Options</h2>
 <p/><ul><li>
 <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>--withcss[=CSSFILE]</code>:  Copy the CSS file to <code>docs/</code> (default is <code>quickdocs.css</code>)</li></li>
+<code>--withcss[=CSSFILE]</code>:  Copy the CSS file to <code>docs/</code> (default is <code>qdox.css</code>)</li></li>
 </ul>
 
 <h2 class="w3-container">Description</h2>
-<p/>  The <code>quickdocs</code> command generates the documentation for a simple Python
+<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.
@@ -50,13 +50,15 @@ <h2 class="w3-container">Description</h2>
 <p/>  You can use your project's <code>pages-build-deployment</code> workflow to deploy the
   documentation to <code>github.io</code> or to your own custom site by setting the
   following options in your project <code>Settings-->Pages</code>:
-<p/>  * <code>Source</code>: Choose <code>Deploy from a branch</code>
-<p/>  * <code>Branch</code>: Choose <code>main</code> and <code>/docs</code>.
-<p/>  * <code>Custom domain</code>: Enter one if you have one.
-<p/>
+<p/><ul><li>
+<code><code>Source</code></code>:  Choose <b>Deploy from a branch</b></li><li>
+<code><code>Branch</code></code>:  Choose <b>main</b> and <b>/docs</b>.</li><li>
+<code><code>Custom domain</code></code>:  Enter one if you have one.</li></li>
+</ul>
+
 <h2 class="w3-container">Usage</h2>
-<p/>  To use <code>quickdocs</code> in a project you must do the following.
-<p/><ol><li> Install <code>quickdocs</code> from the repo into the current <code>venv</code> by running the</li>  command   <pre>python3 -m pip install git+<a href="https://github.com/dchassin/quickdocs" target="_tab">https://github.com/dchassin/quickdocs</a></pre>   <li> Run <code>quickdocs</code> in the project root folder by running the command</li>  <pre>quickdocs -</pre>    If you want to include a CSS file, use the option <code>--withcss=file.css</code>, e.g.,  <pre>quickdocs --withcss=mystyles.css</pre>  <li> Add/push the new files to GitHub by running the commands </li>  <pre>git commit -a -m "Add docs"git push</pre></li>
+<p/>  To use <code>qdox</code> in a project you must do the following.
+<p/><ol><li> Install <code>qdox</code> from the repo into the current <code>venv</code> by running the</li>  command   <pre>python3 -m pip install git+<a href="https://github.com/dchassin/qdox" target="_tab">https://github.com/dchassin/qdox</a></pre>   <li> Run <code>qdox</code> in the project root folder by running the command</li>  <pre>qdox -</pre>    If you want to include a CSS file, use the option <code>--withcss=CSSFILE</code>, e.g.,  <pre>qdox --withcss=mystyles.css</pre>  The <code>CSSFILE</code> defaults to <code>qdox.css</code> when omitted.  <li> Add/push the new files to GitHub by running the commands </li>  <pre>git commit -a -m "Add docs"git push</pre></li>
 </ol>
 
 <h2 class="w3-container">Text Formatting</h2>
@@ -84,12 +86,12 @@ <h2 class="w3-container">Text Formatting</h2>
 
 <h1 id="python" class="w3-container">Python Library</h1>
 
-<h2 class="w3-container"><code><b>QuickdocsError</b>() &rightarrow; <i>None</i></code></h2>
+<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>() &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
+<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
@@ -110,14 +112,14 @@ <h3 class="w3-container">Properties</h3>
 <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><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>quickdocs</td></tr>
+<tr><th><nobr>Name</nobr></th><td>:</td><td>qdox</td></tr>
 <tr><th><nobr>Version</nobr></th><td>:</td><td>0.0.0a0</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>
@@ -127,7 +129,8 @@ <h1 id="package" class="w3-container">Package Metadata</h1>
 <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>
-<tr><th><nobr>Urls</nobr></th><td>:</td><td>Homepage = <a href="https://github.com/dchassin/quickdocs" target="_tab">https://github.com/dchassin/quickdocs</a><br/>Documentation = <a href="https://www.chassin.org/quickdocs" target="_tab">https://www.chassin.org/quickdocs</a><br/>Repository = <a href="https://github.com/dchassin/quickdocs.git" target="_tab">https://github.com/dchassin/quickdocs.git</a><br/>Issues = <a href="https://github.com/dchassin/quickdocs/issues" target="_tab">https://github.com/dchassin/quickdocs/issues</a></td></tr>
+<tr><th><nobr>Urls</nobr></th><td>:</td><td>Homepage = <a href="https://github.com/dchassin/qdox" target="_tab">https://github.com/dchassin/qdox</a><br/>Documentation = <a href="https://www.chassin.org/qdox" target="_tab">https://www.chassin.org/qdox</a><br/>Repository = <a href="https://github.com/dchassin/qdox.git" target="_tab">https://github.com/dchassin/qdox.git</a><br/>Issues = <a href="https://github.com/dchassin/qdox/issues" target="_tab">https://github.com/dchassin/qdox/issues</a></td></tr>
+<tr><th><nobr>Scripts</nobr></th><td>:</td><td><code>qdox</code> &rightarrow; <code>main()</code></td></tr>
 </table>
 <hr/><p/><cite>Copyright &copy; 2024 David P. Chassin</body>
             </html>
diff --git a/docs/quickdocs.css → docs/qdox.css b/docs/quickdocs.css → docs/qdox.css
diff --git a/pyproject.toml b/pyproject.toml
@@ -3,7 +3,7 @@ requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "quickdocs"
+name = "qdox"
 version = "0.0.0a0"
 description = "Generate quick documentation for a Python project on GitHub"
 authors = [
@@ -26,10 +26,10 @@ classifiers = [
     ]
 
 [project.urls]
-Homepage = "https://github.com/dchassin/quickdocs"
-Documentation = "https://www.chassin.org/quickdocs"
-Repository = "https://github.com/dchassin/quickdocs.git"
-Issues = "https://github.com/dchassin/quickdocs/issues"
+Homepage = "https://github.com/dchassin/qdox"
+Documentation = "https://www.chassin.org/qdox"
+Repository = "https://github.com/dchassin/qdox.git"
+Issues = "https://github.com/dchassin/qdox/issues"
 
 [project.scripts]
-quickdocs = "quickdocs:main"
+qdox = "qdox:main"
diff --git a/quickdocs.css → qdox.css b/quickdocs.css → qdox.css
diff --git a/quickdocs.py → qdox.py b/quickdocs.py → qdox.py
@@ -1,6 +1,6 @@
 """Generate docs/index.html from module and README.md
 
-Syntax: quickdocs [OPTION ...]
+Syntax: qdox [OPTION ...]
 
 Options:
 
@@ -10,11 +10,11 @@
 
     * -h|--help|help: Display this help information
 
-    * --withcss[=CSSFILE]: Copy the CSS file to `docs/` (default is `quickdocs.css`)
+    * --withcss[=CSSFILE]: Copy the CSS file to `docs/` (default is `qdox.css`)
 
 Description:
 
-  The `quickdocs` command generates the documentation for a simple Python
+  The `qdox` 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 `help()` and the documentation
   pages.
@@ -28,28 +28,30 @@
   documentation to `github.io` or to your own custom site by setting the
   following options in your project `Settings-->Pages`:
 
-  * `Source`: Choose `Deploy from a branch`
+    * `Source`: Choose **Deploy from a branch**
 
-  * `Branch`: Choose `main` and `/docs`.
+    * `Branch`: Choose **main** and **/docs**.
 
-  * `Custom domain`: Enter one if you have one.
+    * `Custom domain`: Enter one if you have one.
 
 Usage:
 
-  To use `quickdocs` in a project you must do the following.
+  To use `qdox` in a project you must do the following.
 
-    1. Install `quickdocs` from the repo into the current `venv` by running the
+    1. Install `qdox` from the repo into the current `venv` by running the
        command 
        
-         python3 -m pip install git+https://github.com/dchassin/quickdocs
+         python3 -m pip install git+https://github.com/dchassin/qdox
         
-    2. Run `quickdocs` in the project root folder by running the command
+    2. Run `qdox` in the project root folder by running the command
        
-         quickdocs -
+         qdox -
        
-       If you want to include a CSS file, use the option `--withcss=file.css`, e.g.,
+       If you want to include a CSS file, use the option `--withcss=CSSFILE`, e.g.,
        
-         quickdocs --withcss=mystyles.css
+         qdox --withcss=mystyles.css
+
+       The `CSSFILE` defaults to `qdox.css` when omitted.
        
     3. Add/push the new files to GitHub by running the commands 
        
@@ -106,7 +108,7 @@
 import datetime as dt
 import shutil
 
-class QuickdocsError(Exception):
+class QdoxError(Exception):
     """Error caused by an invalid or missing command line option"""
 
 E_OK = 0
@@ -130,9 +132,9 @@ def _main(argv:list[str]=sys.argv):
         if arg == "--debug":
             main.DEBUG = True
         elif key == "--withcss":
-            withcss = value if value else "quickdocs.css"
+            withcss = value if value else "qdox.css"
         elif arg != "-":
-            raise QuickdocsError(f"invalid option '{arg}'")
+            raise QdoxError(f"invalid option '{arg}'")
 
     with open("pyproject.toml","rb") as fh:
         package = tomllib.load(fh)["project"]
@@ -147,8 +149,10 @@ def _main(argv:list[str]=sys.argv):
                 package[item] = "<br/>".join(package[item])
             if not package[item]:
                 package[item] = "None"
+        for item in ["scripts"]:
+            package["scripts"] = "<br/>".join([f"`{x}` &rightarrow; `{y.split(':')[1]}()`" for x,y in package["scripts"].items()])
         for item in list(package):
-            if item not in ["name","version","description","authors","maintainers",
+            if item not in ["name","version","description","authors","maintainers","scripts",
                 "requires-python","dependencies","keywords","license","classifiers","urls"]:
                 del package[item]
 
@@ -158,7 +162,7 @@ def _main(argv:list[str]=sys.argv):
     os.makedirs("docs",exist_ok=True)
 
     if withcss:
-        shutil.copy(withcss,"docs/quickdocs.css")
+        shutil.copy(withcss,"docs/qdox.css")
 
     with open("docs/index.html","w",encoding="utf-8") as html:
 
@@ -236,7 +240,7 @@ def get_mode():
     <head>
         <title>{package_name}</title>
         <meta name="expires" content="86400" />
-        <link rel="stylesheet" href="{withcss if withcss else 'quickdocs.css'}">
+        <link rel="stylesheet" href="{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>
@@ -249,7 +253,7 @@ def get_mode():
         <br/><a href="https://www.chassin.org/">David P. Chassin</a>
         <br/><a href="https://www.eudoxys.com/">Eudoxys Sciences LLC</a>
       </center>
-      <title class="w3-bar-item">{package_name}</title>
+      <title class="w3-bar-item">{package['name']}</title>
       <a href="#main" class="w3-bar-item w3-button">Command Line</a>
       <a href="#python" class="w3-bar-item w3-button">Python Library</a>
       <a href="#package" class="w3-bar-item w3-button">Package Metadata</a>
@@ -398,7 +402,7 @@ def get_mode():
 def main(argv=sys.argv):
     """Main CLI
 
-    Runs the main `quickdocs` program. Generates the `docs/index.html` from
+    Runs the main `qdox` 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
@@ -417,7 +421,7 @@ def main(argv=sys.argv):
     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.
+        QdoxError: exception raised when an invalid command argument is encountered.
     """
     try:
         rc = _main()