# Pydowndoc
Rapidly convert your [AsciiDoc](https://asciidoc.org) files to [Markdown](https://wikipedia.org/wiki/Markdown), using [Python](https://python.org)
A [Python](https://python.org) wrapper around the latest-built binary of [downdoc](https://github.com/opendevise/downdoc); a rapid [AsciiDoc](https://asciidoc.org) to [Markdown](https://wikipedia.org/wiki/Markdown) converter.
## Why Use Pydowndoc?
* Run [downdoc](https://github.com/opendevise/downdoc) from the CLI within your [virtual environment](https://docs.python.org/3/tutorial/venv)
* Use [PyPI](https://pypi.org) as the single installation location of your [Python](https://python.org) project tooling
* Use [the API](pydowndoc/__init__.py) to convert files using your own [Python](https://python.org) code/scripts
* Use the [Hatch](https://hatch.pypa.io) plugin to convert your project’s README.adoc file to [Markdown](https://wikipedia.org/wiki/Markdown), when building your package
## Installation
**Run as a [uv tool](https://docs.astral.sh/uv/guides/tools) (no installation necessary)**
uvx --from Pydowndoc -- downdoc --version
**Add to your [uv project/script’s dependencies](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**
uv add Pydowndoc
**[Install permenantly as a uv tool](https://docs.astral.sh/uv/guides/tools#installing-tools)**
uv tool install Pydowndoc
**Install using [pip](https://pip.pypa.io) after [creating a virtual environment](https://docs.python.org/3/tutorial/venv)**
path/to/venv/python -m pip install Pydowndoc
## CLI Usage
These commands will only work correctly either after installation as a [permenant uv tool](https://docs.astral.sh/uv/guides/tools#installing-tools), or after activating a virtual environment with Pydowndoc installed.
Replace the command name `downdoc` with `uvx --from Pydowndoc -- downdoc`, to run any of the following commands in an ephemeral envrionment.
**Get the currently installed version**
downdoc --version
**Output the help message**
downdoc --help
**Convert a given file (filename will be kept the same, with `.md` file-extension)**
downdoc MyNotes.adoc
**Output the converted file to the given filename**
downdoc MyNotes.adoc -o output.md
**Output the converted file to stdout**
downdoc MyNotes.adoc -o -
**Read the input AsciiDoc file from stdin**
cat MyNotes.adoc | downdoc - -o MyNotes.md
## API Usage
**Convert a given file (the filename will be kept the same, with a `.md` file-extension)**
```python
from pathlib import Path
import pydowndoc
pydowndoc.run(Path("MyNotes.adoc"))
```
**Retrieve the converted file as a string**
```python
from pathlib import Path
import pydowndoc
converted_file_contents: str = pydowndoc.run(
Path("MyNotes.adoc"),
output="-",
process_capture_output=True,
).stdout.decode()
```
**Ensure the conversion process executes successfully**
```python
from pathlib import Path
import pydowndoc
pydowndoc.run(
Path("MyNotes.adoc"),
output=Path("output.md"),
process_check_return_code=True,
)
```
## Use as a Hatch build hook
1. Ensure the `readme` field is added to your `project.dynamic` list within your `pyproject.toml` file
```toml
[project]
name = "my-cool-project"
version = "0.1.0"
dynamic = ["readme"]
```
2. Set up your build backend, within your `pyproject.toml` file
```toml
[build-system]
build-backend = "hatchling.build"
requires = ["hatchling", "Pydowndoc"]
```
3. Include the hook name, so that processing ocurrs
```toml
[tool.hatch.metadata.hooks.downdoc-readme]
```
or
```toml
[tool.hatch.metadata.hooks]
downdoc-readme = {}
```
1. Using a path to a custom [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file
```toml
[tool.hatch.metadata.hooks.downdoc-readme]
path = "README2.adoc"
```
<details>
<summary>A full example of a `+pyproject.toml+` file</summary>
```toml
[project]
name = "my-cool-project"
version = "0.1.0"
dynamic = ["readme"]
[build-system]
build-backend = "hatchling.build"
requires = ["hatchling", "Pydowndoc"]
[tool.hatch.metadata.hooks.downdoc-readme]
path = "README2.adoc"
```
</details>
### Configuration Options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `str` | `README.adoc` | The location of the file to convert to [Markdown](https://wikipedia.org/wiki/Markdown), to be used as the project’s [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file |
## Upgrading
**If [installed as a uv tool](https://docs.astral.sh/uv/guides/tools#upgrading-tools)**
uv tool upgrade Pydowndoc
**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**
uv sync --upgrade-package Pydowndoc
**If installed using [pip](https://pip.pypa.io)**
path/to/venv/python -m pip install --upgrade Pydowndoc
## Uninstallation
**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**
uv remove Pydowndoc
**If installed as a [uv tool](https://docs.astral.sh/uv/guides/tools)**
uv tool uninstall Pydowndoc
**If installed with [pip](https://pip.pypa.io)**
path/to/venv/python -m pip uninstall Pydowndoc
## Reporting Issues
If there are issues with the Python API for this package, or you are encountering installation problems, please report these to [the GitHub issues tracker for this project](https://github.com/CarrotManMatt/Pydowndoc/issues).
If you have problems with the conversion process of your AsciiDoc files to Markdown, please report these [upstream](https://github.com/opendevise/downdoc/issues), directly to the [downdoc project](https://github.com/opendevise/downdoc).
### Windows & macOS Wheels
Windows and macOS wheels are provided to enable use of this project on non-linux hosts.
However, these versions have not had the same level of testing as the linux version.
Therefore, if you encounter any bugs with these other versions, report them to [the GitHub issues tracker for this project](https://github.com/CarrotManMatt/Pydowndoc/issues).
## Licencing
The compiled binary of the distributed downdoc software is shared under the MIT licence as described in [the upstream project’s licence file](https://github.com/opendevise/downdoc?tab=MIT-1-ov-file#readme).
All other code in this project is distrubuted under [the Apache-2.0 licence](./LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "Pydowndoc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Matt Norton <matt@carrotmanmatt.com>",
"keywords": "AsciiDoc, Hatch, Hatchling, Markdown, Python, README, build, converter, documentation, metadata, packaging, pypi, pyproject.toml",
"author": null,
"author_email": "Dan Allen <dan@opendevise.com>, Matt Norton <matt@carrotmanmatt.com>",
"download_url": null,
"platform": null,
"description": "# Pydowndoc\n\n\n\n\n\n\n\n\n\n\nRapidly convert your [AsciiDoc](https://asciidoc.org) files to [Markdown](https://wikipedia.org/wiki/Markdown), using [Python](https://python.org)\n\nA [Python](https://python.org) wrapper around the latest-built binary of [downdoc](https://github.com/opendevise/downdoc); a rapid [AsciiDoc](https://asciidoc.org) to [Markdown](https://wikipedia.org/wiki/Markdown) converter.\n\n## Why Use Pydowndoc?\n\n* Run [downdoc](https://github.com/opendevise/downdoc) from the CLI within your [virtual environment](https://docs.python.org/3/tutorial/venv)\n* Use [PyPI](https://pypi.org) as the single installation location of your [Python](https://python.org) project tooling\n* Use [the API](pydowndoc/__init__.py) to convert files using your own [Python](https://python.org) code/scripts\n* Use the [Hatch](https://hatch.pypa.io) plugin to convert your project\u2019s README.adoc file to [Markdown](https://wikipedia.org/wiki/Markdown), when building your package\n\n## Installation\n\n**Run as a [uv tool](https://docs.astral.sh/uv/guides/tools) (no installation necessary)**\n\nuvx --from Pydowndoc -- downdoc --version\n\n**Add to your [uv project/script\u2019s dependencies](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**\n\nuv add Pydowndoc\n\n**[Install permenantly as a uv tool](https://docs.astral.sh/uv/guides/tools#installing-tools)**\n\nuv tool install Pydowndoc\n\n**Install using [pip](https://pip.pypa.io) after [creating a virtual environment](https://docs.python.org/3/tutorial/venv)**\n\npath/to/venv/python -m pip install Pydowndoc\n\n## CLI Usage\n\nThese commands will only work correctly either after installation as a [permenant uv tool](https://docs.astral.sh/uv/guides/tools#installing-tools), or after activating a virtual environment with Pydowndoc installed.\nReplace the command name `downdoc` with `uvx --from Pydowndoc -- downdoc`, to run any of the following commands in an ephemeral envrionment.\n\n**Get the currently installed version**\n\ndowndoc --version\n\n**Output the help message**\n\ndowndoc --help\n\n**Convert a given file (filename will be kept the same, with `.md` file-extension)**\n\ndowndoc MyNotes.adoc\n\n**Output the converted file to the given filename**\n\ndowndoc MyNotes.adoc -o output.md\n\n**Output the converted file to stdout**\n\ndowndoc MyNotes.adoc -o -\n\n**Read the input AsciiDoc file from stdin**\n\ncat MyNotes.adoc | downdoc - -o MyNotes.md\n\n## API Usage\n\n**Convert a given file (the filename will be kept the same, with a `.md` file-extension)**\n\n```python\nfrom pathlib import Path\n\nimport pydowndoc\n\npydowndoc.run(Path(\"MyNotes.adoc\"))\n```\n\n**Retrieve the converted file as a string**\n\n```python\nfrom pathlib import Path\n\nimport pydowndoc\n\nconverted_file_contents: str = pydowndoc.run(\n Path(\"MyNotes.adoc\"),\n output=\"-\",\n process_capture_output=True,\n).stdout.decode()\n```\n\n**Ensure the conversion process executes successfully**\n\n```python\nfrom pathlib import Path\n\nimport pydowndoc\n\npydowndoc.run(\n Path(\"MyNotes.adoc\"),\n output=Path(\"output.md\"),\n process_check_return_code=True,\n)\n```\n\n## Use as a Hatch build hook\n\n1. Ensure the `readme` field is added to your `project.dynamic` list within your `pyproject.toml` file\n\n ```toml\n [project]\n name = \"my-cool-project\"\n version = \"0.1.0\"\n dynamic = [\"readme\"]\n ```\n2. Set up your build backend, within your `pyproject.toml` file\n\n ```toml\n [build-system]\n build-backend = \"hatchling.build\"\n requires = [\"hatchling\", \"Pydowndoc\"]\n ```\n3. Include the hook name, so that processing ocurrs\n\n ```toml\n [tool.hatch.metadata.hooks.downdoc-readme]\n ```\n\n or\n\n ```toml\n [tool.hatch.metadata.hooks]\n downdoc-readme = {}\n ```\n 1. Using a path to a custom [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file\n\n ```toml\n [tool.hatch.metadata.hooks.downdoc-readme]\n path = \"README2.adoc\"\n ```\n\n<details>\n<summary>A full example of a `+pyproject.toml+` file</summary>\n\n```toml\n[project]\nname = \"my-cool-project\"\nversion = \"0.1.0\"\ndynamic = [\"readme\"]\n\n[build-system]\nbuild-backend = \"hatchling.build\"\nrequires = [\"hatchling\", \"Pydowndoc\"]\n\n[tool.hatch.metadata.hooks.downdoc-readme]\npath = \"README2.adoc\"\n```\n</details>\n\n### Configuration Options\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `path` | `str` | `README.adoc` | The location of the file to convert to [Markdown](https://wikipedia.org/wiki/Markdown), to be used as the project\u2019s [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file |\n\n## Upgrading\n\n**If [installed as a uv tool](https://docs.astral.sh/uv/guides/tools#upgrading-tools)**\n\nuv tool upgrade Pydowndoc\n\n**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**\n\nuv sync --upgrade-package Pydowndoc\n\n**If installed using [pip](https://pip.pypa.io)**\n\npath/to/venv/python -m pip install --upgrade Pydowndoc\n\n## Uninstallation\n\n**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**\n\nuv remove Pydowndoc\n\n**If installed as a [uv tool](https://docs.astral.sh/uv/guides/tools)**\n\nuv tool uninstall Pydowndoc\n\n**If installed with [pip](https://pip.pypa.io)**\n\npath/to/venv/python -m pip uninstall Pydowndoc\n\n## Reporting Issues\n\nIf there are issues with the Python API for this package, or you are encountering installation problems, please report these to [the GitHub issues tracker for this project](https://github.com/CarrotManMatt/Pydowndoc/issues).\n\nIf you have problems with the conversion process of your AsciiDoc files to Markdown, please report these [upstream](https://github.com/opendevise/downdoc/issues), directly to the [downdoc project](https://github.com/opendevise/downdoc).\n\n### Windows & macOS Wheels\n\nWindows and macOS wheels are provided to enable use of this project on non-linux hosts.\nHowever, these versions have not had the same level of testing as the linux version.\nTherefore, if you encounter any bugs with these other versions, report them to [the GitHub issues tracker for this project](https://github.com/CarrotManMatt/Pydowndoc/issues).\n\n## Licencing\n\nThe compiled binary of the distributed downdoc software is shared under the MIT licence as described in [the upstream project\u2019s licence file](https://github.com/opendevise/downdoc?tab=MIT-1-ov-file#readme).\n\nAll other code in this project is distrubuted under [the Apache-2.0 licence](./LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "Python wrapper for converting/reducing AsciiDoc files back to Markdown.",
"version": "1.1.2",
"project_urls": {
"Issues": "https://github.com/CarrotManMatt/Pydowndoc/issues",
"Repository": "https://github.com/CarrotManMatt/Pydowndoc"
},
"split_keywords": [
"asciidoc",
" hatch",
" hatchling",
" markdown",
" python",
" readme",
" build",
" converter",
" documentation",
" metadata",
" packaging",
" pypi",
" pyproject.toml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ccc80295e4d4d9ef56b371001ed94cef77260bd762ba39d23cbd2355792a9a1d",
"md5": "7fb5c81ee3b9579f0f56842055a81e3b",
"sha256": "0cb11ff8227db84c354659ae8c112045ae033c993ffa6eaff7df12752c582b96"
},
"downloads": -1,
"filename": "pydowndoc-1.1.2-py3-none-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "7fb5c81ee3b9579f0f56842055a81e3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 18355669,
"upload_time": "2025-02-03T23:35:15",
"upload_time_iso_8601": "2025-02-03T23:35:15.296853Z",
"url": "https://files.pythonhosted.org/packages/cc/c8/0295e4d4d9ef56b371001ed94cef77260bd762ba39d23cbd2355792a9a1d/pydowndoc-1.1.2-py3-none-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "efba0adb43ed3c89cadc102b9c25ec8a884021c57dcc769749a199ec56d06c96",
"md5": "3cb431a73e587be9f6bd34b997eeab09",
"sha256": "94ad7802a502e062b754016e4ebc5e9049595a4fe466305b78ea028f1c41006b"
},
"downloads": -1,
"filename": "pydowndoc-1.1.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "3cb431a73e587be9f6bd34b997eeab09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17891152,
"upload_time": "2025-02-03T23:35:19",
"upload_time_iso_8601": "2025-02-03T23:35:19.556221Z",
"url": "https://files.pythonhosted.org/packages/ef/ba/0adb43ed3c89cadc102b9c25ec8a884021c57dcc769749a199ec56d06c96/pydowndoc-1.1.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6d6e919c70265182cb79336730c9c87d83084443330b5354ea6699f628ca0172",
"md5": "77c58cfcf8ae9f4bc270cedf5ee9f78f",
"sha256": "d32a0db289498a182134fe89f44358e18fedd60f9770f25141db19367a5c9f31"
},
"downloads": -1,
"filename": "pydowndoc-1.1.2-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "77c58cfcf8ae9f4bc270cedf5ee9f78f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14502811,
"upload_time": "2025-02-03T23:35:24",
"upload_time_iso_8601": "2025-02-03T23:35:24.075697Z",
"url": "https://files.pythonhosted.org/packages/6d/6e/919c70265182cb79336730c9c87d83084443330b5354ea6699f628ca0172/pydowndoc-1.1.2-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 23:35:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CarrotManMatt",
"github_project": "Pydowndoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pydowndoc"
}
JSON
