From f710065b4f9849d8f8b0e322e1c78be30c85b9ad Mon Sep 17 00:00:00 2001 From: Spencer Seidel Date: Wed, 6 Sep 2017 12:39:15 -0400 Subject: 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 --- .../how-to-use-docs/converting-formats.rst | 91 ++++++++++++++++++++++ .../how-to-use-docs/documentation-guide.rst | 59 ++++++++++++++ .../guide/onap-developer/how-to-use-docs/index.rst | 1 + 3 files changed, 151 insertions(+) create mode 100644 docs/guide/onap-developer/how-to-use-docs/converting-formats.rst 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 `_ 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 -t rst myfile.` + +: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 `_ 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 -- cgit 1.2.3-korg