metapensiero.odt2sphinx 2.11

An OpenDocument to reStructuredText/Sphinx converter.

What is it?

Odt2sphinx converts OpenDocument Text .odt file(s) to one or several reStructuredText .rst files.

This is a fork of Christophe de Vienne odt2sphinx.

Install

Python 3 is required!

pip3 install metapensiero.odt2sphinx

Usage

usage: odt2sphinx [-h] [--debug] [--download-source-link] [--embedded-uris]
                  [--ignore-original-column-widths] [--encoding ENCODING]
                  [--test]
                  source [target]

ODT to RST

positional arguments:
  source                Source ODT file to be converted, or a directory
                        containing ODT files and corresponding .expected.rst
                        files in test mode
  target                Either destination directory, a single .rst target
                        filename or "-" for stdout

optional arguments:
  -h, --help            show this help message and exit
  --debug               Emit debug noise
  --download-source-link
                        Add a link to the ODT source file
  --embedded-uris       Emit embedded URIs, instead of anonymous refs
  --ignore-original-column-widths
                        Do not honor the widths of the columns in the original
                        document tables
  --encoding ENCODING   Output encoding, by default UTF-8
  --test                Run in test mode, comparing output with expected reST
                        to be found in “source.expected.rst”

Output files

There are four modes of operation:

1. Sphinx, splitting the source in multiple files, one per chapter

2. Monolithic single plain reST output

3. Stdout

4. Functional test

The first mode is selected by omitting the second positional argument, or giving it the name of a directory. The second is selected by specifying a file name with a .rst extension as the second positional argument. The third by specifying - as the target name. The latter by using the --test option.

Multiple files mode

The files are generated in the target dir, which by default has the same name as the .odt file minus the extension.

At least one file, index.rst, will be written. Depending on the document content, additional rst files may be generated.

Images are extracted and put together in an “images” directory inside the targetdir.

Monolithic output mode

All the output goes into the single rst file specified as the second positional argument.

Images are extracted and put together in an “images” directory inside the directory containing the output file.

Stdout mode

No files are created, even for images: all the output goes to stdout.

Functional test mode

This mode is used by the automatic tests: when the --test option is specified, the tool loads the expected result from a file with the same name as the source one but with the .odt suffix replaced by .expected.rst.

It will print out any discrepancy as a unified diff.

Styles mapping

The following rules will be applied to particulary styles when converting an .odt file. The style names are case-insensitive.

Title

Becomes the main document title (over- and underlined with =)

Subtitle

Becomes the document subtitle (over- and underlined with -)

Title 1 … Title 6

Becomes sub-chapter titles, underlined respectively with #, =, -, ~, + and `; in multiple files mode the source document is splitted on Title 1 sections and a reference to the single files is inserted in a toctree directive in the index.rst file

“Warning” (or “Avertissement”)

The chapter becomes the content of a .. warning directive

“Tip” (or “Trucs & Astuces”)

The chapter becomes the content of a .. tip directive

“Note” or “Information”

The chapter becomes the content of a .. note directive

Changes

2.11 (2015-11-28)

• Support also OpenOffice

• Fix corner case when a line-break follow empty spaces

2.10 (2015-11-26)

• Better recognition of WMF images

2.9 (2015-11-26)

• Recognize fixed text also using the font pitch

• Optimize **bold** **words** as **bold words**

2.8 (2015-11-26)

• Fix error when a table contains empty columns

2.7 (2015-11-24)

• Recurse down document sections

• New option –ignore-original-column-widths, to produce tighter tables

2.6 (2015-11-22)

• Eliminate font style from spans in Anchors, since the textual part of it is taken verbatim by docutils

• Respect original relative widths of table columns

2.5 (2015-11-21)

• Fix compatibility with Python 3.4

• Fix rendering of tables with columns span greater than two

• Aggregate consecutive admonition directives of the same type

2.4 (2015-11-19)

• Fix representation of list item containing a nested list

• Handle table of contents

• By default hyperlinks are rendered using anonymous refs, the new option --embedded-uris reverts to the old behaviour

• Eliminate excessive newlines from the output

• Aggregate consecutive similar elements into a single one

2.3 (2015-11-17)

• Unbreak metafile conversion to PNG

2.2 (2015-11-17)

• Convert also StarView Metafile images to PNG

• Fix issue with table rendering

2.1 (2015-11-17)

• Center cell content of header rows

• Let the content of multi-rows cell flow thru the separator border

• Use LibreOffice to convert Windows Meta File images to PNG

• Restore handling of –download-source-link option

2.0 (2015-11-14)

• Code overhaul, in particular the reST Writer has been rewritten from scratch and the Visitor streamlined

  • reST generation is now done using a stack of objects, easier to understand and to extend

  • honor the auto-numerated and nested list styles

  • handle line breaks in paragraphs

  • honor the title and subtitle of the document, using different decorations than those used for section titles

  • respect the styling of the section titles

  • support multi-rows header in tables

  • handle subscript and superscript text styles

• New automatic tests, comparing the output with an expected result

• Print to stdout alternative mode

1.1 (2015-11-05)

• Fix release version, removing the date tag

1.0 (2015-11-05)

• Forked from https://bitbucket.org/cdevienne/odt2sphinx

• Drop support for Python 2

• Use Pillow instead of PIL

• Rewrap output text for enhanced readability

• Single monolithic alternative mode

0.2.3 (2012-09-06)

• Fix filename generation by replacing any non-alphanumeric character (issue #3).

• Fix handling of non-styled lists.

0.2.2 (2012-07-04)

• Fix the sdist archive on pypi.

0.2.1 (2012-06-24)

• Add support for numbered lists, hyperlinks, underlined text (translated to italic).

• Fix bold text support.

0.2 (2012-05-28)

• Now supports python 3

• Explicitely added PIL as a dependency (issue #2).

0.1.2 (2012-05-22)

• Add “Information” to the styles mapping.

• Handle note, tip and warning styles in lists items. This allows to use lists inside a note, a tip or a warning.

• Now handle external images (issue #1).

0.1.1 (2011-12-20)

• Improved the RstFile for use in third-party code: it is now possible to insert code and not just append it.

• Add a README file

0.1.0

Initial release