summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorSpencer Seidel <jsseidel@fastmail.com>2017-09-06 12:39:15 -0400
committerRich Bennett <rb2745@att.com>2017-09-06 17:48:29 +0000
commitf710065b4f9849d8f8b0e322e1c78be30c85b9ad (patch)
tree7e0c903f659702bb7de7757bc4950a3251445048 /docs
parent2802a98edbdb6964f2cc32a08c09241fc615b870 (diff)
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>
Diffstat (limited to 'docs')
-rw-r--r--docs/guide/onap-developer/how-to-use-docs/converting-formats.rst91
-rw-r--r--docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst59
-rw-r--r--docs/guide/onap-developer/how-to-use-docs/index.rst1
3 files changed, 151 insertions, 0 deletions
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
index 000000000..96b5c82ad
--- /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 6bce35df9..316e0af31 100644
--- 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.
+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
---------
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 48d5aa918..cd387df51 100644
--- 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
+ converting-formats
addendum