Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/flozz/rst2gemtext

Converts reStructuredText to Gemtext (Gemini markup format)
https://github.com/flozz/rst2gemtext

Last synced: 15 days ago
JSON representation

Converts reStructuredText to Gemtext (Gemini markup format)

Awesome Lists containing this project

README 

        
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.8

* 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 `_ on GitHub

* `Ask on Discord `_ (I am not always available to chat, but I try to answer to everyone)



Bugs

~~~~



Please `open an issue `_ 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 `_ 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 `_ and pass tests. `Black `_ and `Flake8 `_ are used on this project to enforce the coding style.



Run the tests

~~~~~~~~~~~~~



You must install `Nox `__ 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.8

    nox --session test-3.9

    nox --session test-3.10

    nox --session test-3.11

    nox --session test-3.12



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 `__

* `💵️ Give me a tip on PayPal `__

* `❤️ Sponsor me on GitHub `__



Changelog

---------



* **[NEXT]** (changes on ``master``, but not released yet):



  * chore: Added Python 3.12 support

  * chore!: Removed Python 3.7 support



* **v0.3.1:**



  * fix: Fixed truncated tables when last row contains bullet lists (@flozz, #1)



* **v0.3.0:**



  * feat: Handle admonitons (``admonition``, ``attention``, ``caution``,

    ``danger``, ``error``, ``hint``, ``important``, ``note``, ``tip`` and

    ``warning`` nodes) (@flozz)



* **v0.2.0:**



  * feat: Pass the source file name to docutils to allow the ``include``

    directive to work (@flozz)

  * feat: Added a basic support of the ``table`` (and associated) 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