docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
   4
   5 .. _converting-to-rst:
   6
   7 Converting to RST
   8 =================
   9
  10 RST format is used for documentation. Other file formats can be converted to
  11 RST with pandoc.
  12
  13 .. caution::
  14
  15   Always check the output text after conversion. For the most common errors,
  16   see section Fixing the converted document.
  17
  18 Installing pandoc
  19 -----------------
  20
  21 Pandoc is a powerful document-transformation utility. We'll use it to
  22 do simple conversions, but it is capable of much more. Visit
  23 the `pandoc website <http://pandoc.org/installing.html>`_ for
  24 installation instructions for your platform.
  25
  26 Converting
  27 ----------
  28
  29 Using a terminal, navigate to the directory containing the documents
  30 you wish to convert. Next, issue the following command for each file
  31 you'd like to convert:
  32
  33 :code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>`
  34
  35 :code:`-s` tells pandoc to produce a standalone document
  36
  37 :code:`--toc` tells pandoc to produce a table of contents (optional)
  38
  39 :code:`-t` tells pandoc to produce reStructuredText output
  40
  41 :code:`-f` tells pandoc the input format. It should be one of the following:
  42
  43 +--------------------+----------------------------------------------------+
  44 | Format             | Description                                        |
  45 +====================+====================================================+
  46 |commonmark          | Markdown variant                                   |
  47 +--------------------+----------------------------------------------------+
  48 |docbook             | XML-based markup                                   |
  49 +--------------------+----------------------------------------------------+
  50 |docx                | Microsoft Word                                     |
  51 +--------------------+----------------------------------------------------+
  52 |epub                | Ebook format                                       |
  53 +--------------------+----------------------------------------------------+
  54 |haddock             | Doc format produced by tool used on Haskell code   |
  55 +--------------------+----------------------------------------------------+
  56 |html                | HTML                                               |
  57 +--------------------+----------------------------------------------------+
  58 |json                | JSON pandoc AST                                    |
  59 +--------------------+----------------------------------------------------+
  60 |latex               | Older typesetting syntax                           |
  61 +--------------------+----------------------------------------------------+
  62 |markdown            | Simple formatting syntax meant to produce HTML     |
  63 +--------------------+----------------------------------------------------+
  64 |markdown_github     | Github flavored markdown                           |
  65 +--------------------+----------------------------------------------------+
  66 |markdown_mmd        | Multi-markdown flavored markdown                   |
  67 +--------------------+----------------------------------------------------+
  68 |markdown_phpextra   | PHP flavored markdown                              |
  69 +--------------------+----------------------------------------------------+
  70 |markdown_strict     | Markdown with no added pandoc features             |
  71 +--------------------+----------------------------------------------------+
  72 |mediawiki           | Popular wiki language                              |
  73 +--------------------+----------------------------------------------------+
  74 |native              | Pandoc native Haskell                              |
  75 +--------------------+----------------------------------------------------+
  76 |odt                 | Open document text (used by LibreOffice)           |
  77 +--------------------+----------------------------------------------------+
  78 |opml                | Outline processor markup language                  |
  79 +--------------------+----------------------------------------------------+
  80 |org                 | Org mode for Emacs                                 |
  81 +--------------------+----------------------------------------------------+
  82 |rst                 | reStructuredText                                   |
  83 +--------------------+----------------------------------------------------+
  84 |t2t                 | Wiki-like formatting syntax                        |
  85 +--------------------+----------------------------------------------------+
  86 |textile             | A formatting syntax similar to RST and markdown    |
  87 +--------------------+----------------------------------------------------+
  88 |twiki               | Popular wiki formatting syntax                     |
  89 +--------------------+----------------------------------------------------+
  90
  91 Fixing the converted document
  92 -----------------------------
  93
  94 How much you'll need to fix the converted document depends on which file
  95 format you're converting from. Here are a couple of things to watch out
  96 for:
  97
  98 1. Multi-line titles need to be converted to single line
  99 2. Standalone "**" characters
 100 3. :code:`***bolded***` should be :code:`**bolded**`
 101 4. Mangled tables
 102
 103 Previewing edits
 104 ----------------
 105
 106 Web-based
 107 ~~~~~~~~~
 108
 109 `Online Sphinx editor <https://livesphinx.herokuapp.com/>`_ is a RST previewing
 110 tool.