Add md2po2md (#162)

* Add 'md2po2md' basic implementation

* Fix test

* Add md2po2md pre-commit hook

* Update 'Useful recipes' documentation section

* Document md2po2md

* Add '--nolocation' option to md2po2md

* Minor change in docs

* Remove useful recipes from docs, moved to tutorial

* Add some tests

* Improve consistency removing '{ext}' placeholder

* Add docs and refactor

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.3.64
+current_version = 0.3.65
 
 [bumpversion:file:mdpo/__init__.py]
 

.pre-commit-config.yaml

@@ -9,12 +9,16 @@ repos:
     rev: v4.0.1
     hooks:
       - id: trailing-whitespace
+        name: trailing-whitespace
       - id: end-of-file-fixer
+        name: end-of-file-fixer
       - id: double-quote-string-fixer
+        name: double-quote-string-fixer
   - repo: https://github.com/asottile/add-trailing-comma
     rev: v2.1.0
     hooks:
       - id: add-trailing-comma
+        name: add-trailing-comma
         args:
           - --py36-plus
   - repo: https://github.com/asottile/setup-cfg-fmt

.pre-commit-hooks.yaml

@@ -0,0 +1,5 @@
+- id: md2po2md
+  name: md2po2md
+  entry: md2po2md
+  description: Translates Markdown files using PO files for a set of predefined language codes creating multiple directories, one for each language
+  language: python

.yamllint

@@ -29,13 +29,15 @@ rules:
   key-ordering:
     ignore: |
       .pre-commit-config.yaml
+      .pre-commit-hooks.yaml
       .github
       .readthedocs.yml
       test/test_po2md/.markdownlint-cli2.yaml
   line-length:
     allow-non-breakable-words: true
-    ignore:
+    ignore: |
       .pre-commit-config.yaml
+      .pre-commit-hooks.yaml
     max: 96
   new-lines:
     type: unix

docs/api.rst

@@ -16,6 +16,12 @@ po2md
 .. automodule:: mdpo.po2md
    :members: pofile_to_markdown
 
+md2po2md
+========
+
+.. automodule:: mdpo.md2po2md
+  :members: markdown_to_pofile_to_markdown
+
 mdpo2html
 =========
 

docs/cli.rst

@@ -60,6 +60,21 @@ The output produced by :ref:`po2md-cli` is compatible with the following
 
    <hr>
 
+.. _md2po2md-cli:
+
+md2po2md
+========
+
+.. sphinx_argparse_cli::
+   :module: mdpo.md2po2md.__main__
+   :func: build_parser
+   :prog: md2po2md
+   :title:
+
+.. raw:: html
+
+   <hr>
+
 .. _mdpo2html-cli:
 
 mdpo2html

docs/devref/index.rst

@@ -17,3 +17,4 @@ mdpo/
    mdpo/md2po/mdpo.md2po.index
    mdpo/mdpo2html/mdpo.mdpo2html.index
    mdpo/po2md/mdpo.po2md.index
+   mdpo/md2po2md/mdpo.md2po2md.index

docs/devref/mdpo/md2po2md/mdpo.md2po2md.__init__.rst

@@ -0,0 +1,6 @@
+***********
+__init__.py
+***********
+
+.. autofunction:: mdpo.md2po2md.markdown_to_pofile_to_markdown
+   :noindex:

docs/devref/mdpo/md2po2md/mdpo.md2po2md.__main__.rst

@@ -0,0 +1,6 @@
+***********
+__main__.py
+***********
+
+.. automodule:: mdpo.md2po2md.__main__
+   :members:

docs/devref/mdpo/md2po2md/mdpo.md2po2md.index.rst

@@ -0,0 +1,9 @@
+*********
+md2po2md/
+*********
+
+.. toctree::
+   :maxdepth: 2
+
+   mdpo.md2po2md.__init__
+   mdpo.md2po2md.__main__

docs/index.rst

@@ -14,14 +14,14 @@ Markdown files translation using pofiles. Fully complies with
    tutorial
    commands
    related-utilities
-   useful-recipes
 
 .. toctree::
    :maxdepth: 2
    :caption: Reference
 
    cli
    api
+   pc-hooks
    changelog
 
 .. toctree::

docs/pc-hooks.rst

@@ -0,0 +1,22 @@
+****************
+pre-commit hooks
+****************
+
+md2po2md
+========
+
+.. code-block:: yaml
+
+   - repo: https://github.com/mondeja/mdpo
+     rev: v0.3.65
+     hooks:
+       - id: md2po2md
+         args:
+           - prueba.md
+           - -l
+           - es
+           - -o
+           - locale/{lang}
+
+.. seealso::
+   * :ref:`md2po2md CLI<md2po2md-cli>`

docs/tutorial.rst

@@ -61,6 +61,39 @@ This will be the output after previous two commands:
 
    <hr>
 
+Simple README file translation
+==============================
+
+Just use :ref:`md2po2md CLI<md2po2md-cli>`:
+
+.. code-block:: bash
+
+  md2po2md README.md -l es -l fr -o "locale/{lang}"
+
+Define the languages to translate into using the ``-l`` option.
+
+You also can use the next snippet to include links for the translations:
+
+.. code-block:: html
+
+  <!-- mdpo-disable -->
+  <!-- mdpo-enable-next-line -->
+  > Read this document in other languages:
+  >
+  > - [Español][readme-es]
+  > - [Français][readme-fr]
+  <!-- mdpo-enable -->
+
+  [readme-es]: https://github.com/user/repo/blob/master/locale/es/README.md
+  [readme-fr]: https://github.com/user/repo/blob/master/locale/fr/README.md
+
+.. seealso::
+   * :ref:`md2po2md CLI<md2po2md-cli>`
+
+.. raw:: html
+
+   <hr>
+
 HTML-from-Markdown to HTML
 ==========================
 

mdpo/__init__.py

@@ -5,7 +5,7 @@
 from mdpo.po2md import pofile_to_markdown
 
 
-__version__ = '0.3.64'
+__version__ = '0.3.65'
 __title__ = 'mdpo'
 __description__ = ('Markdown file translation utilities using PO files')
 __all__ = (

mdpo/cli.py

@@ -4,6 +4,7 @@
 import sys
 
 from mdpo import __version__
+from mdpo.md4c import DEFAULT_MD4C_GENERIC_PARSER_EXTENSIONS
 from mdpo.text import parse_escaped_pairs
 
 
@@ -87,12 +88,13 @@ def parse_metadata_cli_arguments(metadata):
     )
 
 
-def add_common_cli_first_arguments(parser):
-    """Adds common mdpo arguments to an argument parser at the beginning.
+def add_common_cli_first_arguments(parser, quiet=True):
+    """Add common mdpo arguments to an argument parser at the beginning.
 
     Args:
         parser (:py:class:`argparse.ArgumentParser`): Arguments parser to
             extend.
+        quiet (bool): Include the argument ``-q/--quiet``.
     """
     parser.add_argument(
         '-h', '--help', action='help',
@@ -104,14 +106,15 @@ def add_common_cli_first_arguments(parser):
         version=f'%(prog)s {__version__}',
         help='Show program version number and exit.',
     )
-    parser.add_argument(
-        '-q', '--quiet', action='store_true',
-        help='Do not print output to STDOUT.',
-    )
+    if quiet:
+        parser.add_argument(
+            '-q', '--quiet', action='store_true',
+            help='Do not print output to STDOUT.',
+        )
 
 
 def add_common_cli_latest_arguments(parser):
-    """Adds common mdpo arguments to an argument parser at the end.
+    """Add common mdpo arguments to an argument parser at the end.
 
     Args:
         parser (:py:class:`argparse.ArgumentParser`): Arguments parser to
@@ -128,3 +131,53 @@ def add_common_cli_latest_arguments(parser):
              ' you can pass either \'--command-alias "mdpo-on:mdpo-enable"\''
              ' or \'--command-alias "mdpo-on:enable"\' arguments.',
     )
+
+
+def add_extensions_argument(parser):
+    """Add the ``-x/--extension`` argument to an argument parser.
+
+    Args:
+        parser (:py:class:`argparse.ArgumentParser`): Arguments parser to
+            extend.
+    """
+    parser.add_argument(
+        '-x', '--extension', '--ext', dest='extensions', action='append',
+        default=None,
+        help='md4c extension used to parse markdown content formatted as'
+             ' pymd4c extension keyword arguments. This argument can be passed'
+             ' multiple times. If is not passed, next extensions are used:'
+             f' {", ".join(DEFAULT_MD4C_GENERIC_PARSER_EXTENSIONS)}.'
+             ' You can see all available at'
+             ' https://github.com/dominickpastore/pymd4c#parser-option-flags',
+        metavar='EXTENSION',
+    )
+
+
+def add_debug_option(parser):
+    """Add the ``-D/--debug`` option to an argument parser.
+
+    Args:
+        parser (:py:class:`argparse.ArgumentParser`): Arguments parser to
+            extend.
+    """
+    parser.add_argument(
+        '-D', '--debug', dest='debug', action='store_true',
+        help='Print useful messages in the parsing process showing the'
+             ' contents of all Markdown elements.',
+    )
+
+
+def add_nolocation_option(parser):
+    """Add the ``--no-location/--nolocation`` option to an argument parser.
+
+    Args:
+        parser (:py:class:`argparse.ArgumentParser`): Arguments parser to
+            extend.
+    """
+    parser.add_argument(
+        '--no-location', '--nolocation', dest='location', action='store_false',
+        help="Do not write '#: filename:line' lines. Note that using this"
+             ' option makes it harder for technically skilled translators to'
+             " understand each message's context. Same as 'xgettext "
+             "--no-location'.",
+    )

mdpo/md2po/__main__.py

@@ -9,6 +9,9 @@
 from mdpo.cli import (
     add_common_cli_first_arguments,
     add_common_cli_latest_arguments,
+    add_debug_option,
+    add_extensions_argument,
+    add_nolocation_option,
     parse_command_aliases_cli_arguments,
     parse_metadata_cli_arguments,
 )
@@ -91,24 +94,8 @@ def build_parser():
              ' passed as \'-po/--po-filepath\' parameter will be removed.'
              ' Only has effect used in combination with \'--merge-pofiles\'.',
     )
-    parser.add_argument(
-        '--no-location', '--nolocation', dest='location', action='store_false',
-        help="Do not write '#: filename:line' lines. Note that using this"
-             ' option makes it harder for technically skilled translators to'
-             " understand each message's context. Same as 'xgettext "
-             "--no-location'.",
-    )
-    parser.add_argument(
-        '-x', '--extension', '--ext', dest='extensions', action='append',
-        default=None,
-        help='md4c extension used to parse markdown content formatted as'
-             ' pymd4c extension keyword arguments. This argument can be passed'
-             ' multiple times. If is not passed, next extensions are used:'
-             f' {", ".join(DEFAULT_MD4C_GENERIC_PARSER_EXTENSIONS)}.'
-             ' You can see all available at'
-             ' https://github.com/dominickpastore/pymd4c#parser-option-flags',
-        metavar='<EXTENSION>',
-    )
+    add_nolocation_option(parser)
+    add_extensions_argument(parser)
     parser.add_argument(
         '--po-encoding', dest='po_encoding', default=None,
         help='Resulting PO file encoding.', metavar='<ENCODING>',
@@ -147,12 +134,8 @@ def build_parser():
              ' \'-d "Content-Type: text/plain; charset=utf-8"'
              ' -d "Language: es"\'.',
     )
-    parser.add_argument(
-        '-D', '--debug', dest='debug', action='store_true',
-        help='Print useful messages in the parsing process showing the'
-             ' contents of all Markdown elements.',
-    )
     add_common_cli_latest_arguments(parser)
+    add_debug_option(parser)
     return parser
 
 
@@ -213,10 +196,9 @@ def run(args=[]):
             ignore_msgids=opts.ignore_msgids,
             command_aliases=opts.command_aliases,
             metadata=opts.metadata,
+            wrapwidth=opts.wrapwidth,
             debug=opts.debug,
         )
-        if isinstance(opts.wrapwidth, int):
-            kwargs['wrapwidth'] = opts.wrapwidth
 
         pofile = markdown_to_pofile(opts.glob_or_content, **kwargs)