Added new sections

Added sections describing which documentation should be stored on wiki
vs rst, why the doc team chose rst/sphinx, and how to convert from
other formats, loosely based on Steven Wright's video. Updated
index.rst to account for the format-conversion section.

Change-Id: Iea9ec284fc273510177966d8325191ea39d049b2
Issue-Id: DOC-66
Signed-off-by: Spencer Seidel <jsseidel@fastmail.com>

diff --git a/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst b/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst
new file mode 100644 (file)
index 0000000..96b5c82
--- /dev/null
+++ b/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst
@@ -0,0 +1,91 @@
+Converting to RST
+=================
+
+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
+~~~~~~~~~
+
+`rst.ninjs.org <http://rst.ninjs.org>`_ has an excellent RST previewing tool that highlights RST errors with line numbers.
+
+
+

diff --git a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst
index 6bce35d..316e0af 100644 (file)
--- a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst
+++ b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst
@@ -29,6 +29,65 @@ The developer Wiki or other web sites can reference these rendered
 documents directly allowing projects to easily maintain current release
 documentation.
 
 documents directly allowing projects to easily maintain current release
 documentation.
 

+Why reStructuredText/Sphinx?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the past, standard documentation methods included ad-hoc Word documents, PDFs, 
+poorly organized Wikis, and other, often closed, tools like Adobe FrameMaker.
+The rise of DevOps, Agile, and Continuous Integration, however, created a paradigm
+shift for those who care about documentation because:
+
+1. Documentation must be tightly coupled with code/product releases. In many cases,
+particularly with open-source products, many different versions of the same code
+can be installed in various production environments. DevOps personnel must have
+access to the correct version of documentation.
+
+2. Resources are often tight, volunteers scarce. With a large software base
+like ONAP, a small team of technical writers, even if they are also developers,
+cannot keep up with a constantly changing, large code base. Therefore, those closest
+to the code should document it as best they can, and let professional writers edit for
+style, grammar, and consistency.
+
+Plain-text formatting syntaxes, such as reStructuredText, Markdown, and Textile,
+are a good choice for documentation because:
+  a. They are editor agnostic
+  b. The source is nearly as easy to read as the rendered text
+  c. Documentation can be treated exactly as source code is (e.g. versioned,
+diff'ed, associated with commit messages that can be included in rendered docs)
+  d. Shallow learning curve
+
+The documentation team chose reStructuredText largely because of Sphinx, a Python-based
+documentation build system, which uses reStructuredText natively. In a code base
+as large as ONAP's, cross-referencing between component documentation was deemed
+critical. Sphinx and reStructuredText have built-in functionality that makes
+collating and cross-referencing component documentation easier.
+
+Which docs should go where?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Frequently, developers ask where documentation should be created. Should they always use
+reStructuredText/Sphinx? Not necessarily. Is the wiki appropriate for anything at all? Yes.
+
+It's really up to the development team. Here is a simple rule:
+
+The more tightly coupled the documentation is to a particular version of the code,
+the more likely it is that it should be stored with the code in reStructuredText.
+
+Two examples on opposite ends of the spectrum:
+
+Example 1: API documentation is often stored literally as code in the form of formatted
+comment sections. This would be an ideal choice for reStructuredText stored in a doc repo.
+
+Example 2: A high-level document that describes in general how a particular component interacts
+with other ONAP components with charts. The wiki would be a better choice for this.
+
+The doc team encourages component teams to store as much documentation as reStructuredText
+as possible because:
+
+1. The doc team can more easily edit component documentation for grammar, spelling, clarity, and consistency.
+2. A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output.
+3. The doc team can easily re-organize the documentation.
+4. Wiki articles tend to grow stale over time as the people who write them change positions or projects.

 
 Structure
 ---------
 
 Structure
 ---------

diff --git a/docs/guide/onap-developer/how-to-use-docs/index.rst b/docs/guide/onap-developer/how-to-use-docs/index.rst
index 48d5aa9..cd387df 100644 (file)
--- a/docs/guide/onap-developer/how-to-use-docs/index.rst
+++ b/docs/guide/onap-developer/how-to-use-docs/index.rst
@@ -10,4 +10,5 @@ Creating Documentation
    documentation-guide
    style-guide
    include-documentation
    documentation-guide
    style-guide
    include-documentation

+   converting-formats 

    addendum
    addendum