## Key Terms
- `Cell`: An executing module or Markdown container in a Jupyter Notebook.
- `Directive`: A pipe-delineated (`|`) comment block recognized by Quarto and `nbquarto`.
- `Processor`: A class that tailors a cell based on its directives.
## Introducing `nbquarto`: Your Python-Powered Notebook Enhancer
Harness the might of Python with `nbquarto`, a dynamic interface to externally transform Jupyter Notebook cells, designed ideally for [Quarto](https://quarto.org/) projects.
This framework streamlines your documentation process by enabling rapid creation and implementation of post-processors for Jupyter Notebooks.
Although Quarto-focused, `nbquarto` serves as a valuable asset for any Python project leveraging Jupyter Notebooks.
## Getting Started
Check out the installation directions [here](https://muellerzr.github.io/nbquarto) to get started!
## Choose `nbquarto` for a Superior Experience
Drawing inspiration from [nbdev](https://github.com/fastai/nbdev), `nbquarto` steers towards a more comprehensible and less abstracted interface.
It focuses on modifications to Jupyter Notebooks as to fully capitalize on Quarto's abundant features, minimizing dependencies, and enhancing code readability.
## No More Learning Curve with `nbquarto`
Why learn a new language (Lua) to modify content already in Python?
`nbquarto` emerges as the Pythonic alternative to Quarto Extensions. Offering flexibility and simplicity at the cost of a negligible increase in processing time,
`nbquarto` empowers you to control the narrative.
## How Does `nbquarto` Work?
At the heart of `nbquarto` is a `Processor`. This component modifies a cell to fine-tune code formatting or swiftly craft complex Quarto syntax combinations.
Each `cell` object encompasses two crucial elements: `directives_` (a list of cell directives) and `source` (modifiable cell text).
See how easy it is to add a comment to the top of a cell's text source:
```python
>>> from nbquarto import Processor
>>> class BasicProcessor(Processor):
... "A basic processor that adds a comment to the top of a cell's text source."
...
... directives = "process"
...
... def process(self, cell):
... if any(directive in cell.directives_ for directive in self.directives):
... cell.source = f"# This code has been processed!\n{cell.source}"
```
And in a notebook cell:
```python
# Input
>>> #| process
... print("Hello, world!")
# Output
>>> # This code has been processed!
... print("Hello, world!")
```
## Simplified Configuration
Say goodbye to confusion with `nbquarto`'s configuration file. This handy feature organizes processor use, notebook paths, and processor constants for a seamless user experience.
```yaml
documentation_source: tests
processors: [
nbquarto.processors.example:BasicProcessor,
nbquarto.processors.autodoc:AutoDocProcessor
]
processor_args:
AutoDocProcessor:
repo_owner: muellerzr
repo_name: nbquarto
```
## Efficient Notebook Processing
Execute the `nbquarto-process` command to let the configured `Processor`(s) work their magic on your notebooks. All processed notebooks, saved as `qmd` files, land safely in your desired output folder:
```bash
nbquarto-process \
--config_file tests/test_artifacts/single_processor.yaml \
--notebook_file tests/test_artifacts/test_example.ipynb \
--output_folder docs/
```
## `nbdev` Reinvented: Experience `nbquarto`
Transform your understanding of `nbdev` with `nbquarto`, a user-friendly reimagining of the original project.
Bask in the simplicity of an unambiguous interface for modifying Jupyter Notebooks, enjoy the luxury of minimal abstraction,
relish clear error messages, and appreciate the adherence to excellent Python coding practices.
Raw data
{
"_id": null,
"home_page": "https://github.com/muellerzr/nbquarto",
"name": "nbquarto",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "quarto",
"author": "Zachary Mueller",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/74/14/95931383e4eaf628c35d9e7f4315b7187c046afa94ad2ebda7426b7c7161/nbquarto-0.0.1.tar.gz",
"platform": null,
"description": "## Key Terms\n\n- `Cell`: An executing module or Markdown container in a Jupyter Notebook.\n- `Directive`: A pipe-delineated (`|`) comment block recognized by Quarto and `nbquarto`.\n- `Processor`: A class that tailors a cell based on its directives.\n\n## Introducing `nbquarto`: Your Python-Powered Notebook Enhancer\n\nHarness the might of Python with `nbquarto`, a dynamic interface to externally transform Jupyter Notebook cells, designed ideally for [Quarto](https://quarto.org/) projects. \nThis framework streamlines your documentation process by enabling rapid creation and implementation of post-processors for Jupyter Notebooks. \nAlthough Quarto-focused, `nbquarto` serves as a valuable asset for any Python project leveraging Jupyter Notebooks.\n\n## Getting Started\n\nCheck out the installation directions [here](https://muellerzr.github.io/nbquarto) to get started!\n\n## Choose `nbquarto` for a Superior Experience\n\nDrawing inspiration from [nbdev](https://github.com/fastai/nbdev), `nbquarto` steers towards a more comprehensible and less abstracted interface. \nIt focuses on modifications to Jupyter Notebooks as to fully capitalize on Quarto's abundant features, minimizing dependencies, and enhancing code readability.\n\n## No More Learning Curve with `nbquarto`\n\nWhy learn a new language (Lua) to modify content already in Python? \n`nbquarto` emerges as the Pythonic alternative to Quarto Extensions. Offering flexibility and simplicity at the cost of a negligible increase in processing time, \n`nbquarto` empowers you to control the narrative.\n\n## How Does `nbquarto` Work?\n\nAt the heart of `nbquarto` is a `Processor`. This component modifies a cell to fine-tune code formatting or swiftly craft complex Quarto syntax combinations. \nEach `cell` object encompasses two crucial elements: `directives_` (a list of cell directives) and `source` (modifiable cell text).\n\nSee how easy it is to add a comment to the top of a cell's text source:\n\n```python\n>>> from nbquarto import Processor\n\n>>> class BasicProcessor(Processor):\n... \"A basic processor that adds a comment to the top of a cell's text source.\"\n...\n... directives = \"process\"\n...\n... def process(self, cell):\n... if any(directive in cell.directives_ for directive in self.directives):\n... cell.source = f\"# This code has been processed!\\n{cell.source}\"\n```\n\nAnd in a notebook cell:\n```python\n# Input\n>>> #| process\n... print(\"Hello, world!\")\n\n# Output\n>>> # This code has been processed!\n... print(\"Hello, world!\")\n```\n\n## Simplified Configuration\n\nSay goodbye to confusion with `nbquarto`'s configuration file. This handy feature organizes processor use, notebook paths, and processor constants for a seamless user experience.\n\n```yaml\ndocumentation_source: tests\nprocessors: [\n nbquarto.processors.example:BasicProcessor,\n nbquarto.processors.autodoc:AutoDocProcessor\n]\n\nprocessor_args:\n AutoDocProcessor: \n repo_owner: muellerzr\n repo_name: nbquarto\n```\n\n## Efficient Notebook Processing\n\nExecute the `nbquarto-process` command to let the configured `Processor`(s) work their magic on your notebooks. All processed notebooks, saved as `qmd` files, land safely in your desired output folder:\n\n```bash\nnbquarto-process \\\n--config_file tests/test_artifacts/single_processor.yaml \\\n--notebook_file tests/test_artifacts/test_example.ipynb \\\n--output_folder docs/\n```\n\n## `nbdev` Reinvented: Experience `nbquarto`\n\nTransform your understanding of `nbdev` with `nbquarto`, a user-friendly reimagining of the original project. \nBask in the simplicity of an unambiguous interface for modifying Jupyter Notebooks, enjoy the luxury of minimal abstraction, \nrelish clear error messages, and appreciate the adherence to excellent Python coding practices. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A minimal nbdev version, focused on writing quarto extensions",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/muellerzr/nbquarto"
},
"split_keywords": [
"quarto"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6a8eb06ac5aec19287a0d6e6a927207faddbd26365dc4925d84b0cf8e2544eb7",
"md5": "096c5620501a2d20feec720522d13011",
"sha256": "d66d0f444f9a4585dc9091cb5a5fc1bc60f7a417c96ae44f46a14d8cdfc5117e"
},
"downloads": -1,
"filename": "nbquarto-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "096c5620501a2d20feec720522d13011",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 28289,
"upload_time": "2023-06-06T00:12:30",
"upload_time_iso_8601": "2023-06-06T00:12:30.016757Z",
"url": "https://files.pythonhosted.org/packages/6a/8e/b06ac5aec19287a0d6e6a927207faddbd26365dc4925d84b0cf8e2544eb7/nbquarto-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "741495931383e4eaf628c35d9e7f4315b7187c046afa94ad2ebda7426b7c7161",
"md5": "285198df79fa28ee3070ca0c375f7e6c",
"sha256": "a647b0fa4d19340bbeaa2fc2e94dea371632c3c27810b6dddae87a9be1c5618b"
},
"downloads": -1,
"filename": "nbquarto-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "285198df79fa28ee3070ca0c375f7e6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23323,
"upload_time": "2023-06-06T00:12:31",
"upload_time_iso_8601": "2023-06-06T00:12:31.795347Z",
"url": "https://files.pythonhosted.org/packages/74/14/95931383e4eaf628c35d9e7f4315b7187c046afa94ad2ebda7426b7c7161/nbquarto-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-06 00:12:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "muellerzr",
"github_project": "nbquarto",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nbquarto"
}
JSON
