main.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-


"""Generator (build process) for project documentation as a static HTML WebPage

Generator (build process) for project documentation as a static HTML WebPage
Calls other scripts "exportPngFromDiagram.py" and "exportPdfFromHtml.py".

Expects following directory tree:

project_root_directory
├── _www ........ temporary, HTML output of documentation generator
├── content ..... here are all the Markdown files and additional files,
│   │             e.g. screenshots, PDFs
│   ├── any_markdown.md
│   ├── screenshot.png
│   ├── datasheet.pdf
│   └── calculation.xlsx
├── originals ... here are all diagramms which get exported to PNGs
│   ├── diagram.drawio
│   └── diagram.umlet
├── exportPdfFromHtml.py ...... Python exporter script for PDFs from HTML
├── exportPngFromDiagram.py ... Python exporter script for diagrams
├── main.py ................... Python doc generator script
├── page_template.html ........ HTML template for document generator
├── print.css ................. stylesheet for print layout of documentation
├── README.md ................. this file
└── requirements.txt .......... Python requirements for additional libs

It is strongly recommended to setup all necessary parameters in the 
init() function of the file config.py, before running it for the first time."""

import os
import shutil
import subprocess
import sys
import markdown
from config import init
import exportPngFromDiagram
import exportPdfFromHtml

# ---------------------------
def cleanup(parameters):
    aPath = parameters['webDir']
    if os.path.isdir(aPath):
        shutil.rmtree(aPath)
    
    print("DEBUG: cleanup()")


# ---------------------------
def buildDirLayout(parameters):
    os.makedirs(parameters['webDir'])
    
    # copy page.css file if any exists
    filepath = os.path.join(parameters['projectRootDir'], 'page.css')
    if os.path.exists(filepath):
        shutil.copy(filepath, parameters['webDir'])
    
    # copy print.css file if any exists
    filepath = os.path.join(parameters['projectRootDir'], 'print.css')
    if os.path.exists(filepath):
        shutil.copy(filepath, parameters['webDir'])

    print("DEBUG: buildDirLayout()")


# ---------------------------
def load_page_template(parameters):
    fileName = os.path.join(parameters['projectRootDir'], "page_template.html")
    with open(fileName, 'r') as fileObject:
        parameters['pageTemplate'] = fileObject.read()
    
    print("DEBUG: load_page_template()")


# ---------------------------
def create_html_page(parameters):
    html_content = None
    md_all_content = []
    
    # concatenate all Markdown documents in the right sequence
    for md_file in parameters['documentSequence']:
        md_file = os.path.join(parameters['contentDir'], md_file + ".md")

        with open(md_file, 'r') as fileObject:
            md_content = fileObject.read()
        
        md_all_content.append(md_content)
    
    # Initialize Markdown-Builder
    mdBuilder = markdown.Markdown(
        extensions= ['markdown.extensions.extra', 'markdown.extensions.toc'],
        extension_configs= { 'markdown.extensions.toc' : { 'toc_depth' : 2 } },
        output_format = "html5", 
        tab_length = 4,
        smart_emphasis = True
    )

    # save Markdown file
    md_content = ("\n").join(md_all_content)
    md_filepath = os.path.join(parameters['webDir'], parameters['documentName'] + ".md")
    with open(md_filepath, 'w') as fileObject:
        fileObject.write(md_content)

    # generate HTML and save it to file
    # and add temporarily TOC statement for HTML and PDF generation
    html_content = mdBuilder.convert(parameters['tocString'] + md_content)
    
    pageParameters = dict (
        TITLE = parameters['title'],
        CONTENT = html_content,
        CURRENTYEAR = parameters['currentYear'],
        GENERATED = parameters['generated'],
        GENERATED_HUMANREADABLE = parameters['generatedHumanReadable']
    )
    
    html_content = parameters['pageTemplate'].format(**pageParameters)
    html_filepath = os.path.join(parameters['webDir'], parameters['documentName'] + ".html")
    with open(html_filepath, 'w') as fileObject:
        fileObject.write(html_content)
    
    print("DEBUG: create_page( " + parameters['documentName'] + " )")


# ---------------------------
def handle_all_content_files(parameters):

    contentDir = parameters['contentDir']
    files = os.listdir(contentDir)
    for filename in files:
        filepath = os.path.join(contentDir, filename)
        if os.path.isfile(filepath):
            if filename.endswith(".md"):
                pass
            else: 
                # copy any matching file
                shutil.copy(filepath, parameters['webDir'])
        elif os.path.islink(filepath):
            # filter out symbolic links
            pass
        elif os.path.isdir(filepath):
            # copy any matching subdir
            shutil.copytree(filepath, os.path.join(parameters['webDir'], filename))
    
    print("DEBUG: handle_all_content_files()")


# ---------------------------
def handle_all_diagram_files():
    exportPngFromDiagram.run()
    print("DEBUG: handle_all_diagram_files()")


# ---------------------------
def handle_all_pdf_files():
    exportPdfFromHtml.run()
    print("DEBUG: handle_all_pdf_files()")


# ---------------------------
def handle_all_docx_files(parameters):
    md_filepath = os.path.join(parameters['webDir'], parameters['documentName'] + ".md")
    word_filepath = os.path.join(parameters['webDir'], parameters['documentName'] + ".docx")

    user_home_path = os.path.join(
        os.environ['HOMEDRIVE'], os.sep, os.environ['HOMEPATH'])

    apps_installation_root = os.path.join(
        user_home_path, "installations")

    pandoc_path = os.path.join(
        apps_installation_root,
        "pandoc",
        "pandoc.exe"
    )

    command = [
        pandoc_path,
        "--table-of-contents",
        "--toc-depth=2",
        "--from=markdown+footnotes",
        md_filepath,
        "--to=docx",
        "--reference-doc",
        os.path.join(parameters['projectRootDir'], 'custom-reference.docx'),
        "--output",
        word_filepath,
        "--resource-path",
        parameters['webDir']
    ]
    subprocess.run(command)

    print("DEBUG: handle_all_docx_files()")


# ---------------------------
def show_usage():
    usage = ["NAME:", 
             "  main.py", "",
             "SYNOPSIS:",
             "  main.py [--help] [--diagram] [--pdf] [--docx]", "",
             "DESCRIPTION:",
             "  Generator (build process) for project documentation as a static HTML WebPage", "",
             "OPTIONS:",
             "  --help     shows this information", "",
             "  --diagram  calls script 'exportPngFromDiagram.py' during build process",
             "             to generate diagrams out of diagramming files", "",
             "  --pdf      calls script 'exportPdfFromHtml.py' during build process",
             "             to generate PDFs out of generated HTML files",
             "  --docx     generates MS-Word docx out of markdown file"
    ]

    print("\n".join(usage))


# ---------------------------
def handle_cli_parameters():
    print("DEBUG: handle_cli_parameters()")


    run_with_diagram_generation = False
    run_with_pdf_generation = False
    run_with_docx_generation = False

    if len(sys.argv) > 1:
        for pos in range(1, len(sys.argv)):
            parameter = sys.argv[pos].lower()

            if parameter == "--help":
                show_usage()
                exit(1)
            elif parameter == "--diagram":
                run_with_diagram_generation = True
            elif parameter == "--pdf":
                run_with_pdf_generation = True
            elif parameter == "--docx":
                run_with_docx_generation = True
            else:
                print("ERROR: wrong cli parameter!")
                show_usage()
                exit(2)

    return run_with_diagram_generation, run_with_pdf_generation, run_with_docx_generation


# ---------------------------
def run():

    cli_with_diagrams, cli_with_pdfs, cli_with_docx = handle_cli_parameters()
    parameters = init()

    cleanup(parameters)
    buildDirLayout(parameters)
    load_page_template(parameters)

    if cli_with_diagrams:
        print("DEBUG: cli_with_diagrams")
        handle_all_diagram_files()

    create_html_page(parameters)
    handle_all_content_files(parameters)

    if cli_with_docx:
        print("DEBUG: cli_with_docx")
        handle_all_docx_files(parameters)
    
    if cli_with_pdfs:
        print("DEBUG: cli_with_pdfs")
        handle_all_pdf_files()

    print("DEBUG: run()")


# ---------------------------
# MAIN
# ---------------------------
if __name__ == '__main__':
    run()
    print("DEBUG: main() done")