{
"info": {
"author": "Cyrille Rossant",
"author_email": "cyrille.rossant at gmail.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 3 - Alpha",
"Environment :: Console",
"Framework :: IPython",
"Intended Audience :: Developers",
"License :: OSI Approved :: BSD License",
"Natural Language :: English",
"Operating System :: MacOS :: MacOS X",
"Operating System :: POSIX",
"Operating System :: Unix",
"Programming Language :: Python",
"Programming Language :: Python :: 2",
"Programming Language :: Python :: 2.7",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.3",
"Programming Language :: Python :: 3.4",
"Topic :: Software Development :: Libraries",
"Topic :: Text Processing :: Markup"
],
"description": "[](https://travis-ci.org/rossant/ipymd)\n[](https://coveralls.io/r/rossant/ipymd)\n\n# Replace .ipynb with .md in the IPython Notebook\n\nThe goal of ipymd is to replace `.ipynb` notebook files like:\n\n```json\n{\n \"cells\": [\n {\n \"cell_type\": \"markdown\",\n \"source\": [\n \"Here is some Python code:\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"outputs\": [\n {\n \"name\": \"stdout\",\n \"output_type\": \"stream\",\n \"text\": [\n \"Hello world!\\n\"\n ]\n }\n ],\n \"source\": [\n \"print(\\\"Hello world!\\\")\"\n ]\n }\n ...\n ]\n}\n```\n\nwith:\n\n Here is some Python code:\n\n ```python\n >>> print(\"Hello world!\")\n Hello world!\n ```\n\nThe JSON `.ipynb` are removed from the equation, and the conversion happens on the fly. The IPython Notebook becomes an interactive Markdown text editor!\n\nA drawback is that you lose prompt numbers and images (for now).\n\nThis is useful when you write technical documents, blog posts, books, etc.\n\n\n\n## Installation\n\n1. Install ipymd:\n\n To install the latest release version:\n\n ```shell\n pip install ipymd\n ```\n\n Alternatively, to install the development version:\n\n ```shell\n pip install git+https://github.com/rossant/ipymd\n ```\n\n2. **Optional:**\n To interact with `.ipynb` files:\n\n ```shell\n pip install jupyter ipython\n ```\n\n To interact with `.odt` files:\n\n ```shell\n pip install git+https://github.com/eea/odfpy\n ```\n\n3. Open your `jupyter_notebook_config.py`. Here's how to find it:\n\n\n ```\n jupyter notebook --generate-config # generate a default config file\n jupyter --config-dir # find out the path to the config file\n ```\n\n4. Add the following in `jupyter_notebook_config.py`:\n\n ```python\n c.NotebookApp.contents_manager_class = 'ipymd.IPymdContentsManager'\n ```\n\n5. Now, you can open `.md` files in the Notebook.\n\n## Why?\n\n### IPython Notebook\n\nPros:\n\n* Excellent UI for executing code interactively *and* writing text\n\nCons:\n\n* `.ipynb` not git-friendly\n* Cannot easily edit in a text editor\n* Cannot easily edit on GitHub's web interface\n\n\n### Markdown\n\nPros:\n\n* Simple ASCII/Unicode format to write code and text\n* Can easily edit in a text editor\n* Can easily edit on GitHub's web interface\n* Git-friendly\n\nCons:\n\n* No UI to execute code interactively\n\n\n### ipymd\n\nAll pros of IPython Notebook and Markdown, no cons!\n\n\n## How it works\n\n* Write in Markdown in `document.md`\n * Either in a text editor (convenient when working on text)\n * Or in the Notebook (convenient when writing code examples)\n* Markdown cells, code cells and (optionally) notebook metadata are saved in\n the file\n* Collaborators can work on the Markdown document using GitHub's web interface.\n* By convention, a **notebook code cell** is equivalent to a **Markdown code block with explicit `python` syntax highlighting**:\n\n ```\n >>> print(\"Hello world\")\n Hello world\n ```\n\n* **Notebook metadata** can be specified in [YAML](http://yaml.org/) inside\n Jekyll-style [front-matter](http://jekyllrb.com/docs/frontmatter/) dashes\n at the beginning of a document:\n\n ```markdown\n ---\n kernelspec:\n name: some-non-native-kernel\n ---\n\n First cell content\n ```\n\n Native kernel metadata will be elided by default: non-python kernels haven't\n been tested yet, but support is planned.\n\n* **Cell metadata** is specified with YAML stream documents with dashes and\n periods, such as to create slides:\n\n ```markdown\n # Previous slide\n\n ---\n slideshow:\n slide_type: slide\n ...\n\n # Some Slide Content\n ```\n\n > NOTE: You probably shouldn't use `---` to mean an `
`: `***`\n could be a suitable substitute.\n\n* Null metadata (i.e. splitting a markdown cell) can be created with just\n three dashes. This is useful when adding slideshow notes or skipped cells.\n\n ```markdown\n A cell\n\n ---\n\n Another cell\n ```\n\n* The back-and-forth conversion is not strictly the identity function:\n * Extra line breaks in Markdown are discarded\n * Text output and standard output are combined into a single text output (stdout lines first, output lines last)\n\n\n## Caveats\n\n**WARNING**: use this library at your own risks, backup your data, and version-control your notebooks and Markdown files!\n\n* Renaming doesn't work yet (issue #4)\n* New notebook doesn't work yet (issue #5)\n* Only nbformat v4 is supported currently (IPython 3.0)\n\n\n## Formats\n\nipymd uses a modular architecture that lets you define new formats. The following formats are currently implemented, and can be selected by modifying `~/.ipython/profile_/ipython_notebook_config.py`:\n\n* IPython notebook (`.ipynb`)\n* Markdown (`.md`)\n * `c.IPymdContentsManager.format = 'markdown'`\n* [O'Reilly Atlas](http://odewahn.github.io/publishing-workflows-for-jupyter/#1) (`.md` with special HTML tags for code and mathematical equations)\n * `c.IPymdContentsManager.format = 'atlas'`\n* Python (`.py`): code cells are delimited by double line breaks. Markdown cells = Python comments. [TODO: this doesn't work well, see #28 and #31]\n* Opendocument (`.odt`). You need to install the [development version of odfpy](https://github.com/eea/odfpy/).\n\nYou can convert from any supported format to any supported format. This works by converting to an intermediate format that is basically a list of notebook cells.\n\n### ipymd cells\n\nAn **ipymd cell** is a Python dictionary with the following fields:\n\n* `cell_type`: `markdown`, `code` or `notebok_metadata` (if implemented)\n* `input`: a string with the code input (code cell only)\n* `output`: a string with the text output and stdout (code cell only)\n* `source`: a string containing Markdown markup (markdown cell only)\n* `metadata`: a dictionary containing cell (or notebook) metadata\n\n### Kernel Metadata\n\nBy default, notebook metadata for the native kernel (usually `python2` or\n`python3`) won't be written to markdown. Since ipymd doesn't yet support other\nkernels, this doesn't matter much, but if you would like to pick a non-native\npython kernel to be interpreted as the default for ipymd, and store\n`kernelspec` and `language_info` for the other, you can add this to your\n`ipython_notebook_config.py` file:\n * `c.IPymdContentsManager.default_kernel_name = 'python2'`\n\nOr, to always remember all notebook-level metadata:\n * `c.IPymdContentsManager.verbose_metadata = True`\n\n### Customize the Markdown format\n\nYou can customize the exact way the notebook is converted from/to Markdown by deriving from `BaseMarkdownReader` or `MarkdownReader` (idem with writers). Look at `ipymd/formats/markdown.py`.\n\n### Implement your own format\n\nYou can also implement your own format by following these instructions:\n\n* Create a `MyFormatReader` class that implements:\n * `self.read(contents)`: yields ipymd cells from a `contents` string\n* Create a `MyFormatWriter` class that implements:\n * `self.write(cell)`: append an ipymd cell\n * (optional) `self.write_notebook_metadata(cell)`: write the notebook\n metadata dictionary\n * `self.contents`: return the contents as a string\n\n* To activate this format, call this at Notebook launch time (not in a kernel!), perhaps in your `ipython_notebook_config.py`:\n\n```python\n from ipymd import format_manager\n format_manager().register(\n name='my_format',\n reader=MyFormatReader,\n writer=MyFormatWriter,\n file_extension='.md', # or anything else\n file_type='text', # or JSON\n )\n```\n\n* Now you can convert contents: `ipymd.convert(contents, from_='notebook', to='my_format')` or any other combination.\n\n### Contributing a new ipymd format\n* To further integrate your format in ipymd, create a `ipymd/formats/my_format.py` file.\n* Put your reader and writer class in there, as well as a top-level variable:\n\n```python\n MY_FORMAT = dict(\n reader=MyFormatReader,\n writer=MyFormatWriter,\n file_extension='.md',\n file_type='text',\n )\n```\n\n* In `setup.py`, add this to `entry_points`:\n\n```python\n ...\n entry_points={\n 'ipymd.format': [\n ...\n 'my_format=myformat:MY_FORMAT',\n ...\n ]\n }\n```\n\n > Note that the `entry_point` name will be used by default. you may override\n it, if you like, but Don't Repeat Yourself.\n\n* Add some unit tests in `ipymd/formats/tests`.\n* Propose a PR!\n\nLook at the existing format implementations for more details.\n\n\n### Packaging a format\n* If you want to be able to redistribute your format without adding it to ipymd proper (i.e. in-house or experimental), implement all your code in a real python module.\n* Someplace easy to import, e.g. `myformat.py` or `myformat/__init__.py`, add:\n\n```python\n MY_FORMAT = dict(\n reader=MyFormatReader,\n writer=MyFormatWriter,\n file_extension='.md', # or anything else\n file_type='text', # or JSON\n )\n```\n\n and this to your `setup.py`:\n\n```python\n ...\n entry_points={\n 'ipymd.format': [\n 'my_format=myformat:MY_FORMAT',\n ],\n },\n ...\n```\n\n * Publish on pypi!\n * Your users will now be able to `pip install myformat`, then configure their Notebook to use your format with the name `my_format`.",
"description_content_type": null,
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/rossant/ipymd",
"keywords": "",
"license": "BSD",
"maintainer": "",
"maintainer_email": "",
"name": "ipymd",
"package_url": "https://pypi.org/project/ipymd/",
"platform": "UNKNOWN",
"project_url": "https://pypi.org/project/ipymd/",
"project_urls": {
"Homepage": "https://github.com/rossant/ipymd"
},
"release_url": "https://pypi.org/project/ipymd/0.1.3/",
"requires_dist": [
"pyyaml",
"odfpy; extra == 'odf'"
],
"requires_python": "",
"summary": "Use the IPython notebook as an interactive Markdown editor",
"version": "0.1.3"
},
"last_serial": 2733363,
"releases": {
"0.1.0": [],
"0.1.1": [
{
"comment_text": "",
"digests": {
"md5": "bf55ba88a61fb934184dbcac6bec23da",
"sha256": "0782b3be3974fd3fd0f52335160d1e13c905ecbc479ec975834f877d18dfd345"
},
"downloads": -1,
"filename": "ipymd-0.1.1.zip",
"has_sig": false,
"md5_digest": "bf55ba88a61fb934184dbcac6bec23da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 103320,
"upload_time": "2015-06-12T08:10:57",
"url": "https://files.pythonhosted.org/packages/2c/81/81d1a924533c0d419623f89257c389b94536a8ece11ee7d82b3fafbbf62d/ipymd-0.1.1.zip"
}
],
"0.1.2": [
{
"comment_text": "",
"digests": {
"md5": "703f53fd57a3e01259137951fc5bea66",
"sha256": "0c2dc324daa849381478501616389b17cce8a961b235d280bf286ac2ed4f463f"
},
"downloads": -1,
"filename": "ipymd-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "703f53fd57a3e01259137951fc5bea66",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 64538,
"upload_time": "2016-03-25T15:56:08",
"url": "https://files.pythonhosted.org/packages/a6/c2/57b5a98b1ebe12ea6b21e5a5c9cf92478245e97127c75fd9c9af6cb40dfd/ipymd-0.1.2-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "ed4d8ff1c17ef2e272055c96c6f2af6e",
"sha256": "0b3966f1355f91e4b66f8cf4ed82644def4d54f0fdcfb39252fd2d74c80c5d24"
},
"downloads": -1,
"filename": "ipymd-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "ed4d8ff1c17ef2e272055c96c6f2af6e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 61411,
"upload_time": "2016-03-25T15:56:25",
"url": "https://files.pythonhosted.org/packages/af/6e/58359f1912ab368eed5306dcb785b55a4df8a9856196a4b9a3324f82abfb/ipymd-0.1.2.tar.gz"
}
],
"0.1.3": [
{
"comment_text": "",
"digests": {
"md5": "00beb9bdf87803a72356622f50f0927d",
"sha256": "c40adf1c2ecb17d5df839f5bde0e52e3508c4e070ef63c2f4a9bfa1885cf69eb"
},
"downloads": -1,
"filename": "ipymd-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00beb9bdf87803a72356622f50f0927d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 64856,
"upload_time": "2017-03-27T12:13:40",
"url": "https://files.pythonhosted.org/packages/a9/75/073ab703f642c5cf3ae61e51d0f998ac7b68295a52887c27678394455b0c/ipymd-0.1.3-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "9ddb20c17be40d55b0ad2f0dd9e7226e",
"sha256": "cb39ca10dc605160b9d131aa702217c6e432897b790f8c7ad8d9a1b8cc5ad46c"
},
"downloads": -1,
"filename": "ipymd-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "9ddb20c17be40d55b0ad2f0dd9e7226e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 59169,
"upload_time": "2017-03-27T12:13:42",
"url": "https://files.pythonhosted.org/packages/7e/52/23dc02566ce89ec6d255ef39f6919722ed9b1684c556166fa4cecde4aa20/ipymd-0.1.3.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "00beb9bdf87803a72356622f50f0927d",
"sha256": "c40adf1c2ecb17d5df839f5bde0e52e3508c4e070ef63c2f4a9bfa1885cf69eb"
},
"downloads": -1,
"filename": "ipymd-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00beb9bdf87803a72356622f50f0927d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 64856,
"upload_time": "2017-03-27T12:13:40",
"url": "https://files.pythonhosted.org/packages/a9/75/073ab703f642c5cf3ae61e51d0f998ac7b68295a52887c27678394455b0c/ipymd-0.1.3-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "9ddb20c17be40d55b0ad2f0dd9e7226e",
"sha256": "cb39ca10dc605160b9d131aa702217c6e432897b790f8c7ad8d9a1b8cc5ad46c"
},
"downloads": -1,
"filename": "ipymd-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "9ddb20c17be40d55b0ad2f0dd9e7226e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 59169,
"upload_time": "2017-03-27T12:13:42",
"url": "https://files.pythonhosted.org/packages/7e/52/23dc02566ce89ec6d255ef39f6919722ed9b1684c556166fa4cecde4aa20/ipymd-0.1.3.tar.gz"
}
]
}