How doconce/doconce works
Main Components
• Command-Line Interface (CLI) & Entry Points – The “bin” folder and setup.py indicate that users run DocOnce through command-line commands.
• Core Library Modules – The “lib/doconce” directory houses the conversion routines (modules like doconce.py, html.py, latex.py, slides.py, sphinx.py, etc.) as well as shared utilities (common.py, globals.py, etc.).
• Preprocessing and Templating Engine – DocOnce preprocesses the input text using tools like Mako and other preprocessing directives before conversion. This is a logical component in the conversion pipeline.
• Output Formatting Modules – Individual modules for each output format (HTML, LaTeX, slides, etc.) model the modular “factory” or “strategy” patterns.
• Bundled Assets & Themes – The “bundled” directory contains a large set of themes, CSS styles, JS scripts, LaTeX style files, and even Sphinx themes. These serve as static resource libraries that the conversion modules use to generate the final output.
• Configuration and Dependency Management – Files like requirements.txt, setup.py, Dockerfile, and CI/CD workflows in .github/workflows indicate mechanisms for building, testing, and deploying the tool.
• Testing and Documentation – The “test” directory (as well as the rich documentation in the README) signals an overlay of automated testing and documentation generation (via Sphinx and other tools).
• Within the Conversion Engine, illustrate a pipeline:
○ First, the Preprocessor (invoking Mako and any custom preprocessing) cleans and prepares the input.
○ Then, a format-specific “converter” module processes the preprocessed data into an intermediate representation.
○ Last, a Renderer leverages Bundled Assets (themes, styles, templates) to produce final output files.
• External dependencies (e.g., Python libraries installed via pip/conda and CI/CD systems) to indicate that they are used for building, testing, and package management.
• A “Tests” component that interacts with the core modules, ensuring correctness.
Important Architectural Patterns and Technologies
• Modularity & Plug-In Architecture – Each output format (HTML, LaTeX, slides, etc.) is handled by a separate module, promoting ease of extension.
• Layered Conversion Pipeline – Separation of concerns is evident with preprocessing, conversion, and rendering layers. This resembles the factory or pipeline design pattern, enabling clear data flow.
• Asset Bundling – The extensive “bundled” directory is used as a resource library that can be updated independently.
• CI/CD & Deployment – The presence of Dockerfile, GitHub workflows, and dependency files emphasizes continuous integration and deployment practices.
• Use of Standard Python Packaging – setup.py and requirements.txt indicate how the project is installed and maintained.
Final Assembly
• Drill down into each layer to show the various modules.