Enhance CLI and Documentation for Markdown Server and Converter

Author: PtPrashantTripathi

README.rst

@@ -1,9 +1,14 @@
+.. image:: https://raw.githubusercontent.com/PtPrashantTripathi/markdown-server/master/markdownserver-logo.webp
+   :alt: "Markdown Server Logo"
+   :width: 300px
+   :align: center
+
 ===============
 Markdown Server
 ===============
 
 Markdown-server is a simple web application.
-It converts markdown file to HTML and response by `text/html`.
+It converts markdown files to HTML and responds with `text/html`.
 
 How to use
 ==========
@@ -29,63 +34,112 @@ Just try
 Start server
 ------------
 
-You don't need any special preparation to try to start server. Just execute below commands.
+You can install `markdown-server` from **PyPi** or run it directly from the repository.
 
+### Install from PyPi:
+::
+
+    (.venv)$ pip install markdown-server
+    (.venv)$ markdownserver --host localhost --port 8009 --debug
+
+    Bottle v0.12.8 server starting up (using WSGIRefServer())...
+    Listening on http://localhost:8009/
+
+### Install from GitHub:
 ::
 
     $ git clone https://github.com/ohbarye/markdown-server
     $ cd markdown-server
     $ virtualenv .venv
     $ source .venv/bin/activate
     (.venv)$ pip install -r requirements.txt
-    (.venv)$ markdownserver
+    (.venv)$ markdownserver --host localhost --port 8009 --debug
         Bottle v0.12.8 server starting up (using WSGIRefServer())...
         Listening on http://localhost:8009/
 
-Or, you can install from PyPi.
+If the server starts up successfully, browse the below URL and check the converted result.
 
 ::
 
-    (.venv)$ pip install markdown-server
-    (.venv)$ markdownserver
-        Bottle v0.12.8 server starting up (using WSGIRefServer())...
-        Listening on http://localhost:8009/
+    $ open http://localhost:8009/sample.md
 
+MarkdownServer CLI
+------------------
 
-If server start up successfully, browse below URL and check the converted result.
+You can run the `markdownserver` command to start the server with the following examples:
 
+### Example 1: Using Default Arguments
 ::
 
-    $ open http://localhost:8009/sample.md
+    (.venv)$ markdownserver
+
+This will run the server on the default host (`localhost`) and port (`8009`), with debugging disabled.
+
+### Example 2: Custom Host, Port, and Debug
+::
+
+    (.venv)$ markdownserver --host 0.0.0.0 --port 8080 --debug
+
+This will run the server on `0.0.0.0:8080` with debugging enabled, allowing you to access the server from any device on your local network.
+
+**Arguments:**
+- `--host`: Specify the host to run the server on (default is `localhost`).
+- `--port`: Specify the port to run the server on (default is `8009`).
+- `--debug`: Enable or disable debugging mode (default is `False`).
 
 Only Conversion
 ---------------
 
-Additionally, You can use the conversion function alone.
+Additionally, you can use the conversion function alone from the command line.
+
+::
+
+    (.venv)$ markdownconvert source_md_file target_html_file
+
+This will convert the provided markdown file (`source_md_file`) into an HTML file (`target_html_file`).
+
+MarkdownConverter CLI
+---------------------
+
+The `markdownconvert` command can be used with the following options:
 
 ::
 
-    (.venv)$ convert source_md_file target_html_file
+    $ markdownconvert source_md_file target_html_file
+
+**Arguments:**
+- `source_md_file`: The markdown file you want to convert to HTML.
+- `target_html_file`: The output HTML file to save the converted content.
+
+Example:
+
+::
+
+    $ markdownconvert sample.md sample.md.html
+
+This will convert the `sample.md` file into a `sample.md.html` file in the current directory.
 
 --------------
 Do as you like
 --------------
 
-- Markdown server purvey `http://host/[file_name]` URL. This corresponds to `resources/markdown/[file_name]`.You can put any markdown file here.
-
-- Converted file will be placed to `resources/html` directory. Generated html file includes CSS so it's ease to distribute.
-
-- Environment variables like *host name* or *port number* are set in `env.py`. Edit arbitrarily.
+- The Markdown server provides `http://host/[file_name]` URL. You can place any markdown file here.
 
-    ::
+- The converted HTML file will be placed in the `resources/html` directory. The generated HTML file includes CSS for easy distribution.
 
-        ms_port        = '8009'
-        ms_host        = 'localhost'
+Developers Information
+======================
 
+1. **Masato Ohba**
+   - GitHub: `@ohbarye <https://github.com/ohbarye>`
+   .. image:: https://avatars.githubusercontent.com/u/1811616
+      :alt: "Masato Ohba"
+      :width: 200px
 
-- The default markdown engine is Github flavored Markdown. If you want to use another style, add CSS and edit `env.py`.
+2. **Pt. Prashant Tripathi**
+   - GitHub: `@ptprashanttripathi <https://github.com/ptprashanttripathi>`
+   .. image:: https://avatars.githubusercontent.com/u/26687933
+      :alt: "Pt. Prashant Tripathi"
+      :width: 200px
 
-    ::
 
-        css_name       = 'github.css'
-        markdown_type  = 'gfm'

markdownserver-logo.webp

@@ -1,40 +1,8 @@
-from __future__ import absolute_import
-import argparse
-from bottle import route, run, static_file
 from .markdown_converter import MarkdownConverter
-from .env import root_path, ms_host, ms_port, ms_debug
-import os
+from .markdown_server import MarkdownServer
 
-
-parser = argparse.ArgumentParser()
-parser.add_argument('--host')
-parser.add_argument('--port')
-parser.add_argument('--debug', action='store_true')
-args = parser.parse_args()
-
-converter = MarkdownConverter()
-
-
-@route(r'/<resource:re:.*\.md>')
-def gfmize(resource):
-    if resource == 'favicon.ico':
-        return ''
-
-    html_file_name = os.path.basename(converter.convert(resource))
-    if '/' in resource:
-        html_file_name = '/'.join(resource.split('/')[:-1]) + \
-            '/' + html_file_name
-    return static_file(os.path.join('resources/html',
-                                    html_file_name),
-                       root=root_path)
-
-
-def main():
-    run(host=args.host or ms_host,
-        port=args.port or ms_port,
-        debug=args.debug or ms_debug,
-        reloader=False)
-
-
-if __name__ == '__main__':
-    main()
+__author__ = [
+    {"name": "Masato Ohba", "email": "over.rye@gmail.com"},
+    {"name": "Pt. Prashant Tripathi", "email": "ptprashanttripathi@outlook.com"},
+]
+__all__ = ["MarkdownServer", "MarkdownConverter"]

markdownserver/__init__.py

@@ -1,16 +1,14 @@
-from __future__ import print_function
-from __future__ import absolute_import
-from builtins import object
-import markdown as md
-import codecs
 import sys
 import os
-from .env import css_path, ms_encoding, markdown_type, \
-    html_dir, html_extension
+import markdown as md
+import codecs
+import argparse
+from .env import css_path, ms_encoding, markdown_type, html_dir, html_extension
 
 
-class MarkdownConverter(object):
+class MarkdownConverter:
     def __init__(self):
+        """Initialize the converter with the CSS header and footer."""
         css = codecs.open(css_path, encoding=ms_encoding, mode="r")
         self.html_header = (
             """
@@ -35,21 +33,21 @@ def __init__(self):
             """
 
     def convert(self, src, dst=""):
+        """Convert a Markdown file to HTML."""
         code = md.markdown(self.read_md(src), extensions=[markdown_type])
         return self.write_html(code, src, dst)
 
     def read_md(self, file_name):
+        """Read the contents of a Markdown file."""
         workingdir = os.getcwd()
         md_file = codecs.open(
-            os.path.join(workingdir, file_name),
-            encoding=ms_encoding,
-            mode="r"
+            os.path.join(workingdir, file_name), encoding=ms_encoding, mode="r"
         )
         return md_file.read()
 
     def write_html(self, body, file_name, dst):
+        """Write HTML content to a file."""
         html_path = os.path.join(html_dir, file_name + html_extension)
-
         if dst != "":
             html_path = dst
         try:
@@ -63,12 +61,29 @@ def write_html(self, body, file_name, dst):
 
 
 def main():
-    args = sys.argv
-    if len(args) != 3:
-        print("usage: convert source_md_file target_html_file")
-    else:
-        converter = MarkdownConverter()
-        converter.convert(args[1], args[2])
+    """CLI entry point to convert a Markdown file to HTML using argparse."""
+    parser = argparse.ArgumentParser(
+        description="Convert a Markdown file to an HTML file with styling."
+    )
+    parser.add_argument(
+        "source_md_file",
+        metavar="SOURCE_MD_FILE",
+        help="The source Markdown file to convert",
+    )
+    parser.add_argument(
+        "target_html_file",
+        metavar="TARGET_HTML_FILE",
+        help="The destination HTML file to save",
+    )
+
+    args = parser.parse_args()
+
+    # Convert the given Markdown file to HTML
+    converter = MarkdownConverter()
+    html_path = converter.convert(args.source_md_file, args.target_html_file)
+    print(
+        f"Markdown file '{args.source_md_file}' converted to HTML and saved as '{html_path}'"
+    )
 
 
 if __name__ == "__main__":