# Markdown Code Runner
Markdown Code Runner is a tool designed for processing Markdown files with executable code blocks. It automatically executes these blocks and inserts the output into the Markdown file, making it ideal for note-taking and documentation purposes. This tool supports custom inputs, runtime measurement, and caching mechanisms.
## Features
- **Execute Code Blocks**: Automatically runs code within Markdown files and inserts the output.
- **Custom Inputs**: Supports predefined inputs or inputs from standard I/O.
- **Runtime Measurement**: Measures and displays runtime statistics for code blocks.
- **Cache Control**: Allows selective caching of outputs to avoid rerunning code blocks unnecessarily.
## Installation
Markdown Code Runner supports macOS, Linux, and Windows Subsystem for Linux (WSL).
### 1. **Install Dependencies**
Ensure that you have `python3`, `pip`, and `g++` installed. If not, follow the instructions below for your platform:
#### **On macOS:**
1. **Install Homebrew** (if you don’t have it):
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
2. **Install `python3` and `g++`**:
```bash
brew install python
brew install gcc
```
3. **Install `pip`** (if not already installed):
```bash
python3 -m ensurepip --upgrade
```
#### **On Linux (Debian/Ubuntu):**
1. **Update package lists**:
```bash
sudo apt-get update
```
2. **Install `python3`, `pip`, and `g++`**:
```bash
sudo apt-get install -y python3 python3-pip g++
```
#### **On Windows Subsystem for Linux (WSL):**
1. **Update package lists**:
```bash
sudo apt-get update
```
2. **Install `python3`, `pip`, and `g++`**:
```bash
sudo apt-get install -y python3 python3-pip g++
```
### 2. **Install the Markdown Code Runner Package**
After installing the dependencies, install the Markdown Code Runner package via `pip`:
```bash
pip install mdcoderunner
```
### 3. **Configure Paths**
You may need to specify the paths for `python3` and `g++` in the configuration:
1. **Edit `config.py`** (located in the package directory) to specify the paths:
```python
# config.py
PYTHON_LOCATION = 'python3' # Adjust this path if necessary
GPP_LOCATION = 'g++' # Adjust this path if necessary
```
- Replace the paths with the correct locations of `python3` and `g++` on your system.
- On macOS and Linux, you can typically find the paths using `which python3` and `which g++`.
## Definitions
### Code Blocks
A code block in Markdown Code Runner consists of three components: code, input, and output.
#### Example Code Block
````
<codeStart/>
```python
a = input()
print("hello world", a)
```
```input
Siva
```
```output
hello world Siva
```
<codeEnd/>
````
### Special Elements
- **`<codeStart/>`**: Marks the beginning of a code block.
- **`<codeEnd/>`**: Marks the end of a code block.
#### Skipping Code Blocks
To skip a code block during execution, add the `skip` class:
```
<codeStart class="skip"/>
...
<codeEnd/>
```
#### Avoiding Cache
To force a code block to rerun every time without caching the output, use the `nocache` class:
```
<codeStart class="nocache"/>
...
<codeEnd/>
```
#### Runtime Measurement
To measure runtime statistics for a code block, use the `timeit` class in conjunction with `nocache`:
```
<codeStart class="timeit nocache"/>
...
<codeEnd/>
```
## Usage
```bash
usage: mdcoderunner.py [-h] [--clear-outputs] [--create-code-tags] [--clear-code-tags] input_path [output_path]
Process a Markdown file with executable code blocks.
positional arguments:
input_path Path to the input Markdown file.
output_path Path to the output Markdown file (optional). If not provided, the input file will be
overwritten.
optional arguments:
-h, --help Show this help message and exit.
--clear-outputs Clear all code outputs in the Markdown file.
--create-code-tags Wrap code blocks in <codeStart/> and <codeEnd/> tags.
--clear-code-tags Remove <codeStart/> and <codeEnd/> tags from code blocks.
```
## Example Usage
To process a Markdown file, run the following commands:
```bash
mdcoderunner ./assets/hello_world.md ./assets/hello_world_rendered.md
```
```bash
mdcoderunner ./assets/demo.md ./assets/demo_rendered.md
```
## Inspiration
Markdown Code Runner was developed as a tool for preparing for technical interviews, particularly for learning Data Structures and Algorithms (DSA). The goal was to create a lightweight, non-interactive alternative to Jupyter notebooks, enabling seamless note-taking and code execution within Markdown files. This project was built in a single day of focused development.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/SivaSankarS365/Markdown-code-runner",
"name": "mdcoderunner",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Siva Sankar Sajeev",
"author_email": "sivasankars365@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a6/e3/cf97aee1fe2c60a131929e2b5b902c3720e095e4f2dd58459155a292270c/mdcoderunner-1.0.0.tar.gz",
"platform": null,
"description": "# Markdown Code Runner\n\nMarkdown Code Runner is a tool designed for processing Markdown files with executable code blocks. It automatically executes these blocks and inserts the output into the Markdown file, making it ideal for note-taking and documentation purposes. This tool supports custom inputs, runtime measurement, and caching mechanisms.\n\n## Features\n\n\n\n\n\n\n\n- **Execute Code Blocks**: Automatically runs code within Markdown files and inserts the output.\n- **Custom Inputs**: Supports predefined inputs or inputs from standard I/O.\n- **Runtime Measurement**: Measures and displays runtime statistics for code blocks.\n- **Cache Control**: Allows selective caching of outputs to avoid rerunning code blocks unnecessarily.\n\n## Installation\n\nMarkdown Code Runner supports macOS, Linux, and Windows Subsystem for Linux (WSL).\n\n### 1. **Install Dependencies**\n\nEnsure that you have `python3`, `pip`, and `g++` installed. If not, follow the instructions below for your platform:\n\n#### **On macOS:**\n\n1. **Install Homebrew** (if you don\u2019t have it):\n\n ```bash\n /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n ```\n\n2. **Install `python3` and `g++`**:\n\n ```bash\n brew install python\n brew install gcc\n ```\n\n3. **Install `pip`** (if not already installed):\n\n ```bash\n python3 -m ensurepip --upgrade\n ```\n\n#### **On Linux (Debian/Ubuntu):**\n\n1. **Update package lists**:\n\n ```bash\n sudo apt-get update\n ```\n\n2. **Install `python3`, `pip`, and `g++`**:\n\n ```bash\n sudo apt-get install -y python3 python3-pip g++\n ```\n\n#### **On Windows Subsystem for Linux (WSL):**\n\n1. **Update package lists**:\n\n ```bash\n sudo apt-get update\n ```\n\n2. **Install `python3`, `pip`, and `g++`**:\n\n ```bash\n sudo apt-get install -y python3 python3-pip g++\n ```\n\n### 2. **Install the Markdown Code Runner Package**\n\nAfter installing the dependencies, install the Markdown Code Runner package via `pip`:\n\n```bash\npip install mdcoderunner\n```\n\n### 3. **Configure Paths**\n\nYou may need to specify the paths for `python3` and `g++` in the configuration:\n\n1. **Edit `config.py`** (located in the package directory) to specify the paths:\n\n ```python\n # config.py\n\n PYTHON_LOCATION = 'python3' # Adjust this path if necessary\n GPP_LOCATION = 'g++' # Adjust this path if necessary\n ```\n\n - Replace the paths with the correct locations of `python3` and `g++` on your system.\n - On macOS and Linux, you can typically find the paths using `which python3` and `which g++`.\n\n\n## Definitions\n\n### Code Blocks\n\nA code block in Markdown Code Runner consists of three components: code, input, and output.\n\n#### Example Code Block\n\n````\n<codeStart/>\n\n```python\na = input()\nprint(\"hello world\", a)\n```\n\n```input\nSiva\n```\n\n```output\nhello world Siva\n```\n\n<codeEnd/>\n````\n\n### Special Elements\n\n- **`<codeStart/>`**: Marks the beginning of a code block.\n- **`<codeEnd/>`**: Marks the end of a code block.\n\n#### Skipping Code Blocks\n\nTo skip a code block during execution, add the `skip` class:\n\n```\n<codeStart class=\"skip\"/>\n...\n<codeEnd/>\n```\n\n#### Avoiding Cache\n\nTo force a code block to rerun every time without caching the output, use the `nocache` class:\n\n```\n<codeStart class=\"nocache\"/>\n...\n<codeEnd/>\n```\n\n#### Runtime Measurement\n\nTo measure runtime statistics for a code block, use the `timeit` class in conjunction with `nocache`:\n\n```\n<codeStart class=\"timeit nocache\"/>\n...\n<codeEnd/>\n```\n\n## Usage\n\n```bash\nusage: mdcoderunner.py [-h] [--clear-outputs] [--create-code-tags] [--clear-code-tags] input_path [output_path]\n\nProcess a Markdown file with executable code blocks.\n\npositional arguments:\n input_path Path to the input Markdown file.\n output_path Path to the output Markdown file (optional). If not provided, the input file will be\n overwritten.\n\noptional arguments:\n -h, --help Show this help message and exit.\n --clear-outputs Clear all code outputs in the Markdown file.\n --create-code-tags Wrap code blocks in <codeStart/> and <codeEnd/> tags.\n --clear-code-tags Remove <codeStart/> and <codeEnd/> tags from code blocks.\n```\n\n## Example Usage\n\nTo process a Markdown file, run the following commands:\n\n```bash\nmdcoderunner ./assets/hello_world.md ./assets/hello_world_rendered.md\n```\n\n```bash\nmdcoderunner ./assets/demo.md ./assets/demo_rendered.md\n```\n\n## Inspiration\n\nMarkdown Code Runner was developed as a tool for preparing for technical interviews, particularly for learning Data Structures and Algorithms (DSA). The goal was to create a lightweight, non-interactive alternative to Jupyter notebooks, enabling seamless note-taking and code execution within Markdown files. This project was built in a single day of focused development.\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool for running code blocks in Markdown files.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/SivaSankarS365/Markdown-code-runner"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "66b888349da1982c7415d359aac098a8c8184ceac18b7acf95ea8841ec698f60",
"md5": "4a1440daae181ccbac8c1ea4f7bdf8df",
"sha256": "60ec427fa27a3f7e02399d783d5d601a38effe8a7ea7df30142578bc2fabbf1f"
},
"downloads": -1,
"filename": "mdcoderunner-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a1440daae181ccbac8c1ea4f7bdf8df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12016,
"upload_time": "2024-08-16T04:56:29",
"upload_time_iso_8601": "2024-08-16T04:56:29.403266Z",
"url": "https://files.pythonhosted.org/packages/66/b8/88349da1982c7415d359aac098a8c8184ceac18b7acf95ea8841ec698f60/mdcoderunner-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a6e3cf97aee1fe2c60a131929e2b5b902c3720e095e4f2dd58459155a292270c",
"md5": "2e57db7800e03ac4d1b85f03906c4604",
"sha256": "e3a9402f81f1ead22375e5f06aff87605d19f31bd6b0528b26dfa0dad59c9878"
},
"downloads": -1,
"filename": "mdcoderunner-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2e57db7800e03ac4d1b85f03906c4604",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11816,
"upload_time": "2024-08-16T04:56:30",
"upload_time_iso_8601": "2024-08-16T04:56:30.912314Z",
"url": "https://files.pythonhosted.org/packages/a6/e3/cf97aee1fe2c60a131929e2b5b902c3720e095e4f2dd58459155a292270c/mdcoderunner-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-16 04:56:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SivaSankarS365",
"github_project": "Markdown-code-runner",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "mdcoderunner"
}
JSON
