{"id":34099965,"url":"https://github.com/ppatrzyk/merkury","last_synced_at":"2025-12-14T16:06:45.590Z","repository":{"id":62591643,"uuid":"490285943","full_name":"ppatrzyk/merkury","owner":"ppatrzyk","description":"Generate HTML reports from Python scripts","archived":false,"fork":false,"pushed_at":"2025-11-05T19:07:40.000Z","size":583,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-05T21:08:01.945Z","etag":null,"topics":["analytics","data-analysis","data-science","data-visualization","python","reporting","static-site"],"latest_commit_sha":null,"homepage":"https://ppatrzyk.github.io/merkury/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ppatrzyk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-09T13:03:47.000Z","updated_at":"2025-11-05T19:02:11.000Z","dependencies_parsed_at":"2025-11-05T21:06:15.952Z","dependency_job_id":null,"html_url":"https://github.com/ppatrzyk/merkury","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ppatrzyk/merkury","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppatrzyk%2Fmerkury","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppatrzyk%2Fmerkury/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppatrzyk%2Fmerkury/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppatrzyk%2Fmerkury/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ppatrzyk","download_url":"https://codeload.github.com/ppatrzyk/merkury/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppatrzyk%2Fmerkury/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27534025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-06T02:00:06.463Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","data-analysis","data-science","data-visualization","python","reporting","static-site"],"created_at":"2025-12-14T16:06:40.554Z","updated_at":"2025-12-14T16:06:45.580Z","avatar_url":"https://github.com/ppatrzyk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Merkury\n\n_Merkury_ is a command line utility to run Python scripts and render _static_ HTML or Markdown reports with code and produced output. It uses standard `.py` files as input - any valid script that can be run from command line, can also be turned into a report.\n\n- [Example Python report](https://ppatrzyk.github.io/merkury/examples/intro-py.html)\n- [Documentation](https://ppatrzyk.github.io/merkury/)\n\nIt's a lightweight alternative to tools such as [jupyter](https://github.com/jupyter/jupyter) and [papermill](https://github.com/nteract/papermill). While these have their advantages (and [problems](https://www.youtube.com/watch?v=7jiPeIFXb6U)), when everything you need is to generate a report from a data analysis script, they might be an overkill. This project is meant to address that scenario.\n\nNon-goals of the project:\n\n- interactive code execution in the browser (see [jupyter](https://github.com/jupyter/jupyter)),\n- generating data apps that require backend server (see e.g. [dash](https://github.com/plotly/dash)),\n- converting _any_ input into static HTML (see e.g. [nikola](https://github.com/getnikola/nikola)).\n\n## Installation\n\n```\npip3 install merkury\n```\n\n## Usage\n\n```\n$ merkury -h\nmerkury\n\nUsage:\n    merkury [options] \u003cscript\u003e\n\nOptions:\n    -h --help                       Show this screen.\n    -o \u003cfile\u003e, --output \u003cfile\u003e      Specify report file (if missing, \u003cscript_name\u003e_\u003cdate\u003e).\n    -f \u003cformat\u003e, --format \u003cformat\u003e  Specify report format: html (default), md.\n    -a \u003cauthor\u003e, --author \u003cauthor\u003e  Specify author (if missing, user name).\n    -t \u003ctitle\u003e, --title \u003ctitle\u003e     Specify report title (if missing, script file name)\n    -c, --toc                       Generate Table of Contents\n    -v, --version                   Show version and exit.\n```\n\n### PDF reports\n\nIt is also possible to obtain PDF reports with usage of additional conversion tools (e.g., [pandoc](https://github.com/jgm/pandoc)). For example:\n\n```\nmerkury -o /dev/stdout -f md \u003cyour_script\u003e | pandoc --highlight-style=tango -t pdf -o report.pdf\n```\n\nNote, in case your report file contains raw html chunks (such as plots or images), you will need use _wkhtmltopdf_ [pdf engine](https://pandoc.org/MANUAL.html#option--pdf-engine).\n\n## Formatting and plots\n\nIn produced report, code will be broken into sections. Each section ends with a statement printing some output (e.g., `print()`). You can give titles to each section by placing _magic comment_ `#TITLE \u003cyour_section_title\u003e` after line that produces output.\n\n### Python\n\nWhen it comes to report formatting, there are 3 types of outputs in a Python script: Standard `\u003ccode\u003e` block (default), HTML, or Markdown.\n\nBy default _merkury_ treats any output as standard code print and puts it into `\u003ccode\u003e` blocks. If your output is actually HTML or Markdown, you need to indicate that by placing a _magic comment_ after print statement in your script.\n\n#### HTML\n\nYou need to put a comment `#HTML` after a line that outputs raw HTML. For example:\n\n```\nprint(pandas_df.to_html(border=0))\n#HTML\n```\n\nIn addition to writing HTML by hand or using libraries that allow formatting output as HTML, _merkury_ provides [utility functions](merkury/utils.py) to format plots from common libraries. See [plotting docs](https://ppatrzyk.github.io/merkury/plotting.html) for details.\n\n#### Markdown\n\nIt's also possible to render text formatted in markdown. You need to put magic comment `#MARKDOWN` after print statement.\n\nFor example:\n\n```\nprint(\"\"\"\n# I'm a markdown header\n\nList:\n\n* l1\n* l2\n\n\"\"\")\n#MARKDOWN\n```\n\n## Acknowledgements\n\n- frontend: [pico](https://github.com/picocss/pico), [prism](https://github.com/PrismJS/prism), [tabler-icons](https://github.com/tabler/tabler-icons)\n- [SO discussion that inspired this project](https://stackoverflow.com/questions/60297105/python-write-both-commands-and-their-output-to-a-file)\n- [pyreport](https://github.com/joblib/pyreport) - similar but long abandoned project\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppatrzyk%2Fmerkury","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fppatrzyk%2Fmerkury","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppatrzyk%2Fmerkury/lists"}