summaryrefslogtreecommitdiffstats
path: root/docs/guides/onap-documentation/converting-to-rst.rst
blob: edbf1e2196d93c7981a856938a72b2f06ba9a354 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
.. This work is licensed under a Creative Commons Attribution 4.0
.. International License. http://creativecommons.org/licenses/by/4.0
.. Copyright 2017 AT&T Intellectual Property.  All rights reserved.

.. _converting-to-rst:

Converting to RST
=================

RST format is used for documentation. Other file formats can be converted to
RST with pandoc.

.. caution::

  Always check the output text after conversion. For the most common errors,
  see section Fixing the converted document.

Installing pandoc
-----------------

Pandoc is a powerful document-transformation utility. We'll use it to
do simple conversions, but it is capable of much more. Visit
the `pandoc website <http://pandoc.org/installing.html>`_ for
installation instructions for your platform.

Converting
----------

Using a terminal, navigate to the directory containing the documents
you wish to convert. Next, issue the following command for each file
you'd like to convert:

:code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>`

:code:`-s` tells pandoc to produce a standalone document

:code:`--toc` tells pandoc to produce a table of contents (optional)

:code:`-t` tells pandoc to produce reStructuredText output

:code:`-f` tells pandoc the input format. It should be one of the following:

+--------------------+----------------------------------------------------+
| Format             | Description                                        |
+====================+====================================================+
|commonmark          | Markdown variant                                   |
+--------------------+----------------------------------------------------+
|docbook             | XML-based markup                                   |
+--------------------+----------------------------------------------------+
|docx                | Microsoft Word                                     |
+--------------------+----------------------------------------------------+
|epub                | Ebook format                                       |
+--------------------+----------------------------------------------------+
|haddock             | Doc format produced by tool used on Haskell code   |
+--------------------+----------------------------------------------------+
|html                | HTML                                               |
+--------------------+----------------------------------------------------+
|json                | JSON pandoc AST                                    |
+--------------------+----------------------------------------------------+
|latex               | Older typesetting syntax                           |
+--------------------+----------------------------------------------------+
|markdown            | Simple formatting syntax meant to produce HTML     |
+--------------------+----------------------------------------------------+
|markdown_github     | Github flavored markdown                           |
+--------------------+----------------------------------------------------+
|markdown_mmd        | Multi-markdown flavored markdown                   |
+--------------------+----------------------------------------------------+
|markdown_phpextra   | PHP flavored markdown                              |
+--------------------+----------------------------------------------------+
|markdown_strict     | Markdown with no added pandoc features             |
+--------------------+----------------------------------------------------+
|mediawiki           | Popular wiki language                              |
+--------------------+----------------------------------------------------+
|native              | Pandoc native Haskell                              |
+--------------------+----------------------------------------------------+
|odt                 | Open document text (used by LibreOffice)           |
+--------------------+----------------------------------------------------+
|opml                | Outline processor markup language                  |
+--------------------+----------------------------------------------------+
|org                 | Org mode for Emacs                                 |
+--------------------+----------------------------------------------------+
|rst                 | reStructuredText                                   |
+--------------------+----------------------------------------------------+
|t2t                 | Wiki-like formatting syntax                        |
+--------------------+----------------------------------------------------+
|textile             | A formatting syntax similar to RST and markdown    |
+--------------------+----------------------------------------------------+
|twiki               | Popular wiki formatting syntax                     |
+--------------------+----------------------------------------------------+

Fixing the converted document
-----------------------------

How much you'll need to fix the converted document depends on which file
format you're converting from. Here are a couple of things to watch out
for:

1. Multi-line titles need to be converted to single line
2. Standalone "**" characters
3. :code:`***bolded***` should be :code:`**bolded**`
4. Mangled tables

Previewing edits
----------------

Web-based
~~~~~~~~~

`Online Sphinx editor <https://livesphinx.herokuapp.com/>`_ is a RST previewing
tool.