rst2gemtext - Converts reStructuredText to Gemtext (Gemini markup format)
=========================================================================
|GitHub| |License| |Discord| |Github Actions| |Black|
rst2gemtext aims to convert **reStructuredText** markup to **Gemtext**, the markup format used by Gemini. It can be used both as a **Python library** or as a **CLI tool**.
**This project is currently work in progress.**
Requirements
------------
* Python >= 3.7
* docutils
* pygments
Installation
------------
::
pip install rst2gemtext
Usage
-----
Command Line Interface (CLI)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example::
rst2gemtext input.rst output.gmi
Usage::
usage: rst2gemtext [-h] [--print-xml] input_rst output_gemtext
Converts reStructuredText to Gemtext (Gemini markup format)
positional arguments:
input_rst the reStructuredText file to convert
output_gemtext the output Gemtext file
options:
-h, --help show this help message and exit
--print-xml print the reStructuredText DOM as XML for debugging purpose
Inaccurate output? Report bugs to https://github.com/flozz/rst2gemtext/issues
Python Library
~~~~~~~~~~~~~~
Example: Converting a reStructuredText string to a Gemtext string:
.. code-block:: python
import rst2gemtext
output_gemtext = rst2gemtext.convert("my restructured text string")
Example: Converting a reStructuredText file to a Gemtext file:
.. code-block:: python
import rst2gemtext
with open("input.rst", "r") as input_file:
input_rst = input_file.read()
output_gemtext = rst2gemtext.convert(input_rst)
with open("output.gmi", "w") as output_file:
output_file.write(output_gemtext)
Contributing
------------
Questions
~~~~~~~~~
If you have any question, you can:
* `Open an issue <https://github.com/flozz/rst2gemtext/issues>`_ on GitHub
* `Ask on Discord <https://discord.gg/P77sWhuSs4>`_ (I am not always available to chat, but I try to answer to everyone)
Bugs
~~~~
Please `open an issue <https://github.com/flozz/rst2gemtext/issues>`_ on GitHub with as much information as possible if you found a bug:
* Your operating system / Linux distribution (and its version)
* How you installed the software
* All the logs and message outputted by the software
* etc.
If the issue is about the outputted Gemtext (wrong markup, unsupported reStructuredText feature,...), please provide:
* An example reStructuedText document that generates the wrong output or that contains the unsupported syntax
* The wrong Gemtext output (the one currently generated by rst2gemtext)
* The expected Gemtext output
Pull requests
~~~~~~~~~~~~~
Please consider `filing a bug <https://github.com/flozz/rst2gemtext/issues>`_ before starting to work on a new feature; it will allow us to discuss the best way to do it. It is obviously unnecessary if you just want to fix a typo or small errors in the code.
Please note that your code must follow the coding style defined by the `pep8 <https://pep8.org>`_ and pass tests. `Black <https://black.readthedocs.io/en/stable>`_ and `Flake8 <https://flake8.pycqa.org/en/latest>`_ are used on this project to enforce the coding style.
Run the tests
~~~~~~~~~~~~~
You must install `Nox <https://nox.thea.codes/>`__ first::
pip3 install nox
Then you can check for lint error::
nox --session lint
and run the tests::
nox --session test
You can use following commands to run the tests only on a certain Python version (the corresponding Python interpreter must be installed on your machine)::
nox --session test-3.7
nox --session test-3.8
nox --session test-3.9
nox --session test-3.10
nox --session test-3.11
You can also fix coding style errors automatically with::
nox -s black_fix
Support this project
--------------------
Want to support this project?
* `☕️ Buy me a coffee <https://www.buymeacoffee.com/flozz>`__
* `💵️ Give me a tip on PayPal <https://www.paypal.me/0xflozz>`__
* `❤️ Sponsor me on GitHub <https://github.com/sponsors/flozz>`__
Changelog
---------
* **[NEXT]** (changes on ``master``, but not released yet):
* Nothing yet ;)
* **v0.3.1:**
* Fixed truncated tables when last row contains bullet lists (@flozz, #1)
* **v0.3.0:**
* Handle admonitons (``admonition``, ``attention``, ``caution``, ``danger``,
``error``, ``hint``, ``important``, ``note``, ``tip`` and ``warning``
nodes) (@flozz)
* **v0.2.0:**
* Pass the source file name to docutils to allow the ``include`` directive to
work (@flozz)
* Added a basic support of the ``table`` (and associatad) nodes (@flozz)
* **v0.1.0:**
* Initial release.
* Supported rst nodes:
* block_quote
* bullet_list
* caption
* comment
* emphasis
* enumerated_list
* figure
* image
* list_item
* literal
* literal_block
* paragraph
* raw
* reference
* section
* strong
* substitution_definition
* substitution_reference
* system_message
* target
* Text
* title
* transition
.. |GitHub| image:: https://img.shields.io/github/stars/flozz/rst2gemtext?label=GitHub&logo=github
:target: https://github.com/flozz/rst2gemtext
.. |License| image:: https://img.shields.io/github/license/flozz/rst2gemtext
:target: https://github.com/flozz/rst2gemtext/blob/master/COPYING
.. |Discord| image:: https://img.shields.io/badge/chat-Discord-8c9eff?logo=discord&logoColor=ffffff
:target: https://discord.gg/P77sWhuSs4
.. |Github Actions| image:: https://github.com/flozz/rst2gemtext/actions/workflows/python-ci.yml/badge.svg
:target: https://github.com/flozz/rst2gemtext/actions
.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://black.readthedocs.io/en/stable
Raw data
{
"_id": null,
"home_page": "https://github.com/flozz/rst2gemtext",
"name": "rst2gemtext",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "restructuredtext rst convert gemtext gmi gemini docutils",
"author": "Fabien LOISON",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/5e/da/1b033f8c8fbcf5050efc9d5d2a22ecabff4436470b04a6e821ccd5f38223/rst2gemtext-0.3.1.tar.gz",
"platform": null,
"description": "rst2gemtext - Converts reStructuredText to Gemtext (Gemini markup format)\n=========================================================================\n\n|GitHub| |License| |Discord| |Github Actions| |Black|\n\nrst2gemtext aims to convert **reStructuredText** markup to **Gemtext**, the markup format used by Gemini. It can be used both as a **Python library** or as a **CLI tool**.\n\n**This project is currently work in progress.**\n\n\nRequirements\n------------\n\n* Python >= 3.7\n* docutils\n* pygments\n\n\nInstallation\n------------\n\n::\n\n pip install rst2gemtext\n\n\nUsage\n-----\n\nCommand Line Interface (CLI)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nExample::\n\n rst2gemtext input.rst output.gmi\n\nUsage::\n\n usage: rst2gemtext [-h] [--print-xml] input_rst output_gemtext\n\n Converts reStructuredText to Gemtext (Gemini markup format)\n\n positional arguments:\n input_rst the reStructuredText file to convert\n output_gemtext the output Gemtext file\n\n options:\n -h, --help show this help message and exit\n --print-xml print the reStructuredText DOM as XML for debugging purpose\n\n Inaccurate output? Report bugs to https://github.com/flozz/rst2gemtext/issues\n\n\nPython Library\n~~~~~~~~~~~~~~\n\nExample: Converting a reStructuredText string to a Gemtext string:\n\n.. code-block:: python\n\n import rst2gemtext\n output_gemtext = rst2gemtext.convert(\"my restructured text string\")\n\nExample: Converting a reStructuredText file to a Gemtext file:\n\n.. code-block:: python\n\n import rst2gemtext\n\n with open(\"input.rst\", \"r\") as input_file:\n input_rst = input_file.read()\n\n output_gemtext = rst2gemtext.convert(input_rst)\n\n with open(\"output.gmi\", \"w\") as output_file:\n output_file.write(output_gemtext)\n\n\nContributing\n------------\n\nQuestions\n~~~~~~~~~\n\nIf you have any question, you can:\n\n* `Open an issue <https://github.com/flozz/rst2gemtext/issues>`_ on GitHub\n* `Ask on Discord <https://discord.gg/P77sWhuSs4>`_ (I am not always available to chat, but I try to answer to everyone)\n\n\nBugs\n~~~~\n\nPlease `open an issue <https://github.com/flozz/rst2gemtext/issues>`_ on GitHub with as much information as possible if you found a bug:\n\n* Your operating system\u00a0/ Linux distribution (and its version)\n* How you installed the software\n* All the logs and message outputted by the software\n* etc.\n\nIf the issue is about the outputted Gemtext (wrong markup, unsupported reStructuredText feature,...), please provide:\n\n* An example reStructuedText document that generates the wrong output or that contains the unsupported syntax\n* The wrong Gemtext output (the one currently generated by rst2gemtext)\n* The expected Gemtext output\n\n\nPull requests\n~~~~~~~~~~~~~\n\nPlease consider `filing a bug <https://github.com/flozz/rst2gemtext/issues>`_ before starting to work on a new feature; it will allow us to discuss the best way to do it. It is obviously unnecessary if you just want to fix a typo or small errors in the code.\n\nPlease note that your code must follow the coding style defined by the `pep8 <https://pep8.org>`_ and pass tests. `Black <https://black.readthedocs.io/en/stable>`_ and `Flake8 <https://flake8.pycqa.org/en/latest>`_ are used on this project to enforce the coding style.\n\n\nRun the tests\n~~~~~~~~~~~~~\n\nYou must install `Nox <https://nox.thea.codes/>`__ first::\n\n pip3 install nox\n\nThen you can check for lint error::\n\n nox --session lint\n\nand run the tests::\n\n nox --session test\n\nYou can use following commands to run the tests only on a certain Python version (the corresponding Python interpreter must be installed on your machine)::\n\n nox --session test-3.7\n nox --session test-3.8\n nox --session test-3.9\n nox --session test-3.10\n nox --session test-3.11\n\nYou can also fix coding style errors automatically with::\n\n nox -s black_fix\n\n\nSupport this project\n--------------------\n\nWant to support this project?\n\n* `\u2615\ufe0f Buy me a coffee <https://www.buymeacoffee.com/flozz>`__\n* `\ud83d\udcb5\ufe0f Give me a tip on PayPal <https://www.paypal.me/0xflozz>`__\n* `\u2764\ufe0f Sponsor me on GitHub <https://github.com/sponsors/flozz>`__\n\n\nChangelog\n---------\n\n* **[NEXT]** (changes on ``master``, but not released yet):\n\n * Nothing yet ;)\n\n* **v0.3.1:**\n\n * Fixed truncated tables when last row contains bullet lists (@flozz, #1)\n\n* **v0.3.0:**\n\n * Handle admonitons (``admonition``, ``attention``, ``caution``, ``danger``,\n ``error``, ``hint``, ``important``, ``note``, ``tip`` and ``warning``\n nodes) (@flozz)\n\n* **v0.2.0:**\n\n * Pass the source file name to docutils to allow the ``include`` directive to\n work (@flozz)\n * Added a basic support of the ``table`` (and associatad) nodes (@flozz)\n\n* **v0.1.0:**\n\n * Initial release.\n * Supported rst nodes:\n\n * block_quote\n * bullet_list\n * caption\n * comment\n * emphasis\n * enumerated_list\n * figure\n * image\n * list_item\n * literal\n * literal_block\n * paragraph\n * raw\n * reference\n * section\n * strong\n * substitution_definition\n * substitution_reference\n * system_message\n * target\n * Text\n * title\n * transition\n\n\n.. |GitHub| image:: https://img.shields.io/github/stars/flozz/rst2gemtext?label=GitHub&logo=github\n :target: https://github.com/flozz/rst2gemtext\n\n.. |License| image:: https://img.shields.io/github/license/flozz/rst2gemtext\n :target: https://github.com/flozz/rst2gemtext/blob/master/COPYING\n\n.. |Discord| image:: https://img.shields.io/badge/chat-Discord-8c9eff?logo=discord&logoColor=ffffff\n :target: https://discord.gg/P77sWhuSs4\n\n.. |Github Actions| image:: https://github.com/flozz/rst2gemtext/actions/workflows/python-ci.yml/badge.svg\n :target: https://github.com/flozz/rst2gemtext/actions\n\n.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://black.readthedocs.io/en/stable\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Converts reStructuredText to Gemtext (Gemini markup format)",
"version": "0.3.1",
"split_keywords": [
"restructuredtext",
"rst",
"convert",
"gemtext",
"gmi",
"gemini",
"docutils"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "65fda4472afa1448adc8b0b4ec5fc8f7f27c9531a4f498f40a42f492901d858a",
"md5": "6f12cb1172ec36b970ce65ba0b483fac",
"sha256": "86f32ff3b1471181ce2d29f9cf94b37f6586d1739687e5aa08063e11e5d42ef0"
},
"downloads": -1,
"filename": "rst2gemtext-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f12cb1172ec36b970ce65ba0b483fac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 21994,
"upload_time": "2023-04-16T11:08:17",
"upload_time_iso_8601": "2023-04-16T11:08:17.639712Z",
"url": "https://files.pythonhosted.org/packages/65/fd/a4472afa1448adc8b0b4ec5fc8f7f27c9531a4f498f40a42f492901d858a/rst2gemtext-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5eda1b033f8c8fbcf5050efc9d5d2a22ecabff4436470b04a6e821ccd5f38223",
"md5": "9d4cf97fefef4414762401c45635674a",
"sha256": "1758a94165986a7dd5abcf93e941d2662bca01bb9960542ba1c01c9c7c7e3e35"
},
"downloads": -1,
"filename": "rst2gemtext-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "9d4cf97fefef4414762401c45635674a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21791,
"upload_time": "2023-04-16T11:08:19",
"upload_time_iso_8601": "2023-04-16T11:08:19.378177Z",
"url": "https://files.pythonhosted.org/packages/5e/da/1b033f8c8fbcf5050efc9d5d2a22ecabff4436470b04a6e821ccd5f38223/rst2gemtext-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-16 11:08:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "flozz",
"github_project": "rst2gemtext",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "rst2gemtext"
}
JSON
