# 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.
## Features
* Use [PyPI](https://pypi.org) as the single installation location of your [Python](https://python.org) project tooling
* Run [downdoc](https://github.com/opendevise/downdoc) from the CLI within your [virtual environment](https://docs.python.org/3/tutorial/venv)
* 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)**
uvx Pydowndoc --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)**
python -m pip install Pydowndoc
## CLI Usage
<details>
<summary>If installed using {labelled-url-pip}, or as a {url-uv-wiki-tools-installing}[permenantly installed uv tool], an alias to the original command name (`+downdoc+`) is available</summary>
downdoc --version
</details>
**Get the currently installed version**
uvx Pydowndoc --version
**Run using the command alias**
uvx --from Pydowndoc downdoc --version
**Output the help message**
uvx Pydowndoc --help
**Convert a given file (filename will be kept the same, with `.md` file-format)**
uvx Pydowndoc MyNotes.adoc
**Output the converted file to the given filename**
uvx Pydowndoc MyNotes.adoc -o output.md
**Output the converted file to stdout**
uvx Pydowndoc MyNotes.adoc -o -
**Read the input AsciiDoc file from stdin**
cat MyNotes.adoc | uvx Pydowndoc - -o MyNotes.md
## API Usage
**Convert a given file (the filename will be kept the same, with a `.md` file-format)**
```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
converted_file_contents: str = pydowndoc.run(
Path("MyNotes.adoc"),
output=Path("output.md"),
process_check_return_code=True,
).stdout.decode()
```
## Using 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]
```
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)**
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)**
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).
## 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\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## Features\n\n* Use [PyPI](https://pypi.org) as the single installation location of your [Python](https://python.org) project tooling\n* Run [downdoc](https://github.com/opendevise/downdoc) from the CLI within your [virtual environment](https://docs.python.org/3/tutorial/venv)\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)**\n\nuvx Pydowndoc --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)**\n\npython -m pip install Pydowndoc\n\n## CLI Usage\n\n<details>\n<summary>If installed using {labelled-url-pip}, or as a {url-uv-wiki-tools-installing}[permenantly installed uv tool], an alias to the original command name (`+downdoc+`) is available</summary>\n\ndowndoc --version\n</details>\n\n**Get the currently installed version**\n\nuvx Pydowndoc --version\n\n**Run using the command alias**\n\nuvx --from Pydowndoc downdoc --version\n\n**Output the help message**\n\nuvx Pydowndoc --help\n\n**Convert a given file (filename will be kept the same, with `.md` file-format)**\n\nuvx Pydowndoc MyNotes.adoc\n\n**Output the converted file to the given filename**\n\nuvx Pydowndoc MyNotes.adoc -o output.md\n\n**Output the converted file to stdout**\n\nuvx Pydowndoc MyNotes.adoc -o -\n\n**Read the input AsciiDoc file from stdin**\n\ncat MyNotes.adoc | uvx Pydowndoc - -o MyNotes.md\n\n## API Usage\n\n**Convert a given file (the filename will be kept the same, with a `.md` file-format)**\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\nconverted_file_contents: str = pydowndoc.run(\n Path(\"MyNotes.adoc\"),\n output=Path(\"output.md\"),\n process_check_return_code=True,\n).stdout.decode()\n```\n\n## Using 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 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\npython -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\npython -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## 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.0.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": "16b78496663b733a99c55ebd71fc8cdd8f71bb3d6fcd1f0cd8ad4509aaee733a",
"md5": "a885ccb9c4ac5eb14681272f08c1c433",
"sha256": "7b0dc66f1acae847791800b4e77b58be42a507077e6759779356dee395ffffb9"
},
"downloads": -1,
"filename": "pydowndoc-1.0.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "a885ccb9c4ac5eb14681272f08c1c433",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17890969,
"upload_time": "2024-12-16T00:27:04",
"upload_time_iso_8601": "2024-12-16T00:27:04.732012Z",
"url": "https://files.pythonhosted.org/packages/16/b7/8496663b733a99c55ebd71fc8cdd8f71bb3d6fcd1f0cd8ad4509aaee733a/pydowndoc-1.0.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 00:27:04",
"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
