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