benoitbryon / rst2rst

Transform reStructuredText documents. Standardize RST syntax.

rst2rst

This project provides a docutils [1] writer that produces reStructuredText [2]. It allows users to transform RST documents, as an example, to standardize or beautify RST syntax.

A rst2rst command is also provided.

The project was initiated as an utility for a style guide for Sphinx-based documentations [3]. See also the original ticket [4].

Ressources

• code repository [5]
• bugtracker [6]

References

[1]	http://docutils.sourceforge.net/

[2]	http://docutils.sourceforge.net/rst.html

[3]	http://documentation-style-guide-sphinx.readthedocs.org

[4]	benoitbryon/documentation-style-guide-sphinx#8

[5]	https://github.com/benoitbryon/rst2rst

[6]	https://github.com/benoitbryon/rst2rst/issues

rst2rst's Issues

Use a continuous integration service?

Let's try http://travis-ci.org/

Display version: as rst2rst.version and via rst2rst --version

Once installed, version info should be available via 2 ways:

Via Python:

>>> import rst2rst
>>> rst2rst.version
0.2

Via the rst2rst shell command:

$# bin/rst2rst --version
0.2

Upgrade known good set of versions (KGS) to docutils 0.10 (or latest)

Develop against latest docutils version => upgrade versions in https://github.com/benoitbryon/rst2rst/blob/master/buildout.cfg
See also #18.

NotImplementedError: rst2rst.writer.RSTTranslator visiting unknown node type: docinfo

While processing new_life_of_petunia_dursley.rst (from https://gitlab.com/mcepl/petunia_dursley/) I got this error with rst2rst from the master HEAD:

matej@mitmanek: petunia_dursley (master *%)$ rst2rst --traceback new_life_of_petunia_dursley.rst /tmp/petunia.rst
Traceback (most recent call last):
  File "/home/matej/.local/bin/rst2rst", line 11, in <module>
    load_entry_point('rst2rst==0.3.dev0', 'console_scripts', 'rst2rst')()
  File "/home/matej/.local/lib/python2.7/site-packages/rst2rst/scripts/rst2rst.py", line 14, in main
    description=description)
  File "/home/matej/.local/lib/python2.7/site-packages/docutils/core.py", line 354, in publish_cmdline
    config_section=config_section, enable_exit_status=enable_exit_status)
  File "/home/matej/.local/lib/python2.7/site-packages/docutils/core.py", line 219, in publish
    output = self.writer.write(self.document, self.destination)
  File "/home/matej/.local/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/matej/.local/lib/python2.7/site-packages/rst2rst/writer.py", line 83, in translate
    self.document.walkabout(self.visitor)
  File "/home/matej/.local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/matej/.local/lib/python2.7/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/home/matej/.local/lib/python2.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/home/matej/.local/lib/python2.7/site-packages/docutils/nodes.py", line 1907, in unknown_visit
    % (self.__class__, node.__class__.__name__))
NotImplementedError: rst2rst.writer.RSTTranslator visiting unknown node type: docinfo
matej@mitmanek: petunia_dursley (master *%)$

``rst2rst --version`` echoes version number

rst2rst --version echoes version number to standard output.

Implement standard text roles

See:

• Text roles documentation
• parser implementation

Run tests with several versions of docutils

#18 introduces support for both docutils 0.10 and 0.9.1.

We need to run tests with all the versions...

... or explicitely require docutils >= 0.10. But since #18 supports both, let's do it :)

Try https://pypi.python.org/pypi/tox/ and see whether it makes it easy.
Or, maybe, propose another tool.

=> As a developer, in order to make sure code works with several versions of docutils, I want make test to run tests against several environments.

Split tests/test_fixtures.py into smaller parts

Have some "packaging.py" for PEP396TestCase and "writer.py" for WriterTestCase.
See also changelog related to #18.

Use zest.releaser to perform releases

zest.releaser will simplify release process, i.e. #2 and future updates.

Add masklinn to AUTHORS

See #18.
@masklinn: I added you in AUTHORS, with data from git log. Feel free to change your signature ;)

Register the project with PyPI

Upload to PyPI !

Support for links

rst2rst is translating links into garbage. Is this due to incompatibility with the latest docutils? (I noticed that I had to get rid of a bunch of unused imports just to get rst2rst to run without import errors.)

$ pip-2.7 freeze | grep docutils
docutils==0.10

$ rst2rst
ImportError: No module named error_reporting

After removing many unused imports, it runs.

diff --git a/rst2rst/writer.py b/rst2rst/writer.py
index 1e6ca81..a1cb9f4 100644
--- a/rst2rst/writer.py
+++ b/rst2rst/writer.py
@@ -4,13 +4,8 @@ __docformat__ = 'reStructuredText'

 from textwrap import TextWrapper

-import docutils
-from docutils import frontend, nodes, utils, writers, languages, io
-from docutils.error_reporting import SafeString
-from docutils.transforms import writer_aux
-from docutils.math import unichar2tex, pick_math_environment
-from docutils.math.latex2mathml import parse_latex_math
-from docutils.math.math2html import math2html
+from docutils import nodes
+from docutils import writers


 class Options(object):

$ cat input.rst

pyformat
========

.. image:: https://travis-ci.org/myint/pyformat.png?branch=master
   :target: https://travis-ci.org/myint/pyformat
   :alt: Build status

Formats Python code (using autoflake_, autopep8_, docformatter_, etc.).

.. _autoflake: https://github.com/myint/autoflake
.. _autopep8: https://github.com/hhatto/autopep8
.. _docformatter: https://github.com/myint/docformatter

$ rst2rst input.rst

########
pyformat
########

Formats Python code (using

autoflake

,

autopep8

,

docformatter

, etc.).

Installation of PyPI package at version 0.1 fails

>>> bin/pip install rst2rst
Downloading/unpacking rst2rst
  Running setup.py egg_info for package rst2rst
    Traceback (most recent call last):
      File "<string>", line 14, in <module>
      File "/home/benoit/web/toto/build/rst2rst/setup.py", line 15, in <module>
        version=read_relative_file('version.txt').strip(),
      File "/home/benoit/web/toto/build/rst2rst/setup.py", line 10, in read_relative_file
        with open(os.path.join(os.path.dirname(__file__), filename)) as f:
    IOError: [Errno 2] No such file or directory: '/home/benoit/web/toto/build/rst2rst/version.txt'
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):

  File "<string>", line 14, in <module>

  File "/home/benoit/web/toto/build/rst2rst/setup.py", line 15, in <module>

    version=read_relative_file('version.txt').strip(),

  File "/home/benoit/web/toto/build/rst2rst/setup.py", line 10, in read_relative_file

    with open(os.path.join(os.path.dirname(__file__), filename)) as f:

IOError: [Errno 2] No such file or directory: '/home/benoit/web/toto/build/rst2rst/version.txt'

Implement PEP 396: rst2rst.__version__

See http://www.python.org/dev/peps/pep-0396/
Add a version attribute in rst2rst.init.py

Not Python 2.5 compatible

Requires #26, follows #19.

It almost works in Python 2.5 too: there are a pair of with which require from future import with_statement imports, and 3 str.format() calls which would have to be replaced by %

Support for Python 2.5 is not a high priority as of 2013-05-24: implementation of rst elements is more important. That said, if #26 is implemented, we can work on this ticket.

Run tests against multiple versions of Python

See also #24.

Try https://pypi.python.org/pypi/tox/ and see whether it makes it easy.
Or, maybe, propose another tool.

Implement "proof-of-concept" rst2rst command

See original feature request at benoitbryon/documentation-style-guide-sphinx#8

Proof of concept implementation could be:

Feature: script which transforms RST files to RST
  In order to apply style guide conventions on existing RST files
  As a documentation writer
  I want to run a script which does most of the work automatically

  Scenario: apply style guide recommendations on an existing RST file
    Given a file named `example.txt`
    And this file contains valid RST content
    And the title of the document doesn't use `#` (sharp) character with overline
    And other titles don't use `#` (sharp) character
    When I run `rst2rst` script with `example.txt` as argument
    Then the RST content is displayed on the standard output
    And the title of the document uses  `#` (sharp) character with overline.

Install with Python 2.7 + docutils 0.10 fails

@myint reported in #15:

$ python2.7 setup.py install
$ pip-2.7 freeze | grep docutils
docutils==0.10
$ rst2rst
ImportError: No module named error_reporting

What version of docutils are you using?

As of version 0.2, rst2rst was developed against docutils 0.9.1

• on PyPI, publish a 0.2.1 version which requires docutils > 0.9 and < 0.10
• Upgrade development branch to latest docutils
• Perhaps make a new release which supports docutils 0.10. Check if it can support both 0.9 and 0.10 (is tox made for that?).

NotImplementedError, unknown node type: literal

Using rst2rst command at commit 919b8a4
While trying to transform the README https://github.com/benoitbryon/rst2rst/blob/919b8a496eaa7279fabc07b1a236ecffb92fa5e8/README.rst
Got the following error:

NotImplementedError: rst2rst.writer.RSTTranslator departing unknown node type: literal

In README, make development status clear

Make it clear that rst2rst is "in development".
setup.py already reports "Development Status :: 3 - Alpha" but that's quite invisible on PyPI.
Something like: "in development ; many reStructuredTextElements aren't supported ; help is welcome".

Travis tests failing

All builds..

if [ ! -x /home/travis/build/jayvdb/rst2rst/bin/buildout ]; then /home/travis/virtualenv/python2.7.9/bin/python /home/travis/build/jayvdb/rst2rst/lib/buildout/bootstrap.py -c /home/travis/build/jayvdb/rst2rst/etc/buildout.cfg --version=1.7.1 --distribute buildout:directory=/home/travis/build/jayvdb/rst2rst; fi
Traceback (most recent call last):
  File "/home/travis/build/jayvdb/rst2rst/lib/buildout/bootstrap.py", line 160, in <module>
    options.setup_source).read().replace('\r\n', '\n')
...
  File "/opt/python/2.7.9/lib/python2.7/urllib2.py", line 558, in http_error_default
    raise HTTPError(req.get_full_url(), code, msg, hdrs, fp)
urllib2.HTTPError: HTTP Error 404: Not Found
make: *** [buildout] Error 1

Add tests

• modify the makefile so that make tests is available
• modify the buildout to install testing utilities
• implement a "proof of concept" testcase that compares theoric output (stored in a file) and real output (generated with the writer)