Update READMEs and add documentation for fluent.pygments (#148)

Our READMEs on the fluent packages are lacking. Create some,
and use them in setup.py to add better content on pypi.

Also convert to restructuredText to align with rest of docs.

The documentation for fluent.pygments is really just to demo
the highlighting.

Author: Pike

.gitignore

@@ -1,5 +1,8 @@
 .tox
+.vscode
 *.pyc
 .eggs/
 *.egg-info/
 _build
+build
+dist

README.md

@@ -0,0 +1,47 @@
+Project Fluent
+==============
+
+This is a collection of Python packages to use the `Fluent localization
+system <http://projectfluent.org/>`__.
+
+python-fluent consists of these packages:
+
+``fluent.syntax``
+-----------------
+
+The `syntax package <fluent.syntax>`_ includes the parser, serializer, and traversal
+utilities like Visitor and Transformer. You’re looking for this package
+if you work on tooling for Fluent in Python.
+
+``fluent.runtime``
+------------------
+
+The `runtime package <fluent.runtime>`__ includes the library required to use Fluent to localize
+your Python application. It comes with a ``Localization`` class to use,
+based on an implementation of ``FluentBundle``. It uses the tooling parser above
+to read Fluent files.
+
+``fluent.pygments``
+-------------------
+
+A `plugin for pygments <fluent.pygments>`_ to add syntax highlighting to Sphinx.
+
+Discuss
+-------
+
+We’d love to hear your thoughts on Project Fluent! Whether you’re a
+localizer looking for a better way to express yourself in your language,
+or a developer trying to make your app localizable and multilingual, or
+a hacker looking for a project to contribute to, please do get in touch
+on the mailing list and the IRC channel.
+
+-  Mozilla Discourse: https://discourse.mozilla.org/c/fluent
+-  Matrix channel:
+   `#fluent:mozilla.org <https://chat.mozilla.org/#/room/#fluent:mozilla.org>`__
+
+Get Involved
+------------
+
+python-fluent is open-source, licensed under the Apache License, Version
+2.0. We encourage everyone to take a look at our code and we’ll listen
+to your feedback.

README.rst

@@ -5,24 +5,31 @@ python-fluent
 The :py:mod:`python-fluent` project contains several packages to
 bring `Project Fluent <https://projectfluent.org>`__ to Python.
 Visit the `Github project <https://github.com/projectfluent/python-fluent>`__
-for the full list. Two packages in particular are of general interest
+for the full list. Three packages in particular are of general interest
 and documented here.
 
 fluent.syntax
 -------------
 
-``fluent-syntax`` is the package to use for tooling, analysis, and
+``fluent.syntax`` is the package to use for tooling, analysis, and
 processing of Fluent files.
 
 fluent.runtime
 --------------
 
-``fluent-runtime`` is the reference runtime implementation for
+``fluent.runtime`` is the reference runtime implementation for
 Fluent in Python.
 
+fluent.pygments
+---------------
+
+``fluent.pygments`` can be used to add syntax highlighting for
+Fluent files to Sphinx documentation.
+
 .. toctree::
    :caption: Packages
    :maxdepth: 1
 
    fluent.syntax <https://projectfluent.org/python-fluent/fluent.syntax/>
    fluent.runtime <https://projectfluent.org/python-fluent/fluent.runtime/>
+   fluent.pygments <https://projectfluent.org/python-fluent/fluent.pygments/>

docs/index.rst

@@ -0,0 +1,29 @@
+fluent.pygments
+===============
+
+A plugin for pygments to add `Fluent`_ syntax highlighting to Sphinx.
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install fluent.pygments
+
+
+Usage
+-----
+
+.. code-block:: rst
+
+
+   .. code-block:: fluent
+
+      my-message = a localized string
+
+
+The `documentation`_ has an example of Fluent content
+highlighted with ``fluent.pygments``.
+
+.. _fluent: https://projectfluent.org/
+.. _documentation: https://projectfluent.org/python-fluent/fluent.pygments

fluent.pygments/README.rst

@@ -0,0 +1,44 @@
+Fluent Syntax Highlighting
+==========================
+
+The :py:mod:`fluent.pygments` library is built to do syntax highlighting
+for `Fluent`_ files in Sphinx.
+
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install fluent.pygments
+
+
+Usage
+-----
+
+.. code-block:: rst
+
+
+   .. code-block:: fluent
+
+      my-key = Localize { -brand-name }
+
+Example
+-------
+
+.. code-block:: fluent
+
+   ### A resource comment for the whole file
+
+   my-key = Localize { -brand-name }
+   -brand-name = Fluent
+
+   # $num is the number of strings to localize
+   plurals = { $num ->
+     [one] One string
+    *[other] {$num} strings
+   }
+   an error ;-)
+   Most-strings = are just simple strings.
+
+.. _fluent: https://projectfluent.org/

fluent.pygments/docs/index.rst

@@ -1,3 +1,6 @@
+[metadata]
+version=0.1.0
+
 [bdist_wheel]
 universal=1
 

fluent.pygments/setup.cfg

@@ -1,10 +1,15 @@
 #!/usr/bin/env python
 from setuptools import setup
+import os
+
+this_directory = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(this_directory, 'README.rst'), 'rb') as f:
+    long_description = f.read().decode('utf-8')
 
 setup(name='fluent.pygments',
-      version='0.1.0',
       description='Pygments lexer for Fluent.',
-      long_description='See https://github.com/projectfluent/python-fluent/ for more info.',
+      long_description=long_description,
+      long_description_content_type='text/x-rst',
       author='Mozilla',
       author_email='l10n-drivers@mozilla.org',
       license='APL 2',
@@ -20,4 +25,4 @@
       packages=['fluent', 'fluent.pygments'],
       tests_require=['six'],
       test_suite='tests.pygments'
-)
+      )

fluent.pygments/setup.py

@@ -0,0 +1,19 @@
+fluent.runtime |fluent.runtime|
+===============================
+
+Use `Fluent`_ to localize your Python application. It comes with a ``Localization``
+class to use, based on an implementation of ``FluentBundle``. It uses the parser from
+``fluent.syntax`` to read Fluent files.
+
+.. code-block:: python
+
+    >>> from datetime import date
+    >>> l10n = DemoLocalization("today-is = Today is { $today }")
+    >>> val = l10n.format_value("today-is", {"today": date.today() })
+    >>> val
+    'Today is Jun 16, 2018'
+
+Find the full documentation on https://projectfluent.org/python-fluent/fluent.runtime/.
+
+.. _fluent: https://projectfluent.org/
+.. |fluent.runtime| image:: https://github.com/projectfluent/python-fluent/workflows/fluent.runtime/badge.svg

fluent.runtime/README.rst

@@ -153,7 +153,7 @@ passed through locale aware functions:
 
     >>> from datetime import date
     >>> l10n = DemoLocalization("today-is = Today is { $today }")
-    >>> val = bundle.format_value("today-is", {"today": date.today() })
+    >>> val = l10n.format_value("today-is", {"today": date.today() })
     >>> val
     'Today is Jun 16, 2018'
 

fluent.runtime/docs/usage.rst

@@ -1,10 +1,16 @@
 #!/usr/bin/env python
 from setuptools import setup
+import os
+
+this_directory = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(this_directory, 'README.rst'), 'rb') as f:
+    long_description = f.read().decode('utf-8')
 
 
 setup(name='fluent.runtime',
       description='Localization library for expressive translations.',
-      long_description='See https://github.com/projectfluent/python-fluent/ for more info.',
+      long_description=long_description,
+      long_description_content_type='text/x-rst',
       author='Luke Plant',
       author_email='L.Plant.98@cantab.net',
       license='APL 2',

fluent.runtime/setup.py

@@ -0,0 +1,22 @@
+``fluent.syntax`` |fluent.syntax|
+---------------------------------
+
+Read, write, and transform `Fluent`_ files.
+
+This package includes the parser, serializer, and traversal
+utilities like Visitor and Transformer. You’re looking for this package
+if you work on tooling for Fluent in Python.
+
+.. code-block:: python
+
+   >>> from fluent.syntax import parse, ast, serialize
+   >>> resource = parse("a-key = String to localize")
+   >>> resource.body[0].value.elements[0].value = "Localized string"
+   >>> serialize(resource)
+   'a-key = Localized string\n'
+
+
+Find the full documentation on https://projectfluent.org/python-fluent/fluent.syntax/.
+
+.. _fluent: https://projectfluent.org/
+.. |fluent.syntax| image:: https://github.com/projectfluent/python-fluent/workflows/fluent.syntax/badge.svg

fluent.syntax/README.rst

@@ -1,9 +1,15 @@
 #!/usr/bin/env python
 from setuptools import setup
+import os
+
+this_directory = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(this_directory, 'README.rst'), 'rb') as f:
+    long_description = f.read().decode('utf-8')
 
 setup(name='fluent.syntax',
       description='Localization library for expressive translations.',
-      long_description='See https://github.com/projectfluent/python-fluent/ for more info.',
+      long_description=long_description,
+      long_description_content_type='text/x-rst',
       author='Mozilla',
       author_email='l10n-drivers@mozilla.org',
       license='APL 2',

fluent.syntax/setup.py

@@ -69,7 +69,7 @@ if __name__ == "__main__":
         '--to-publish', dest='pre_pub', action='store_true',
         help='Use this to publish to Github. Builds faster without.'
     )
-    default_docs = ['.', 'fluent.syntax', 'fluent.runtime']
+    default_docs = ['.', 'fluent.syntax', 'fluent.pygments', 'fluent.runtime']
     parser.add_argument(
         '--doc', action='append', choices=default_docs,
         help='Only build select documentation roots.'