Comparison and Recommendation of Document Tool Chain

Comparison for current Tools

Characteristic	Proposed for ONAP	Example from OPNFV	Current ONAP & Examples	Other Option or Examples

Characteristic	Proposed for ONAP	Example from OPNFV	Current ONAP & Examples	Other Option or Examples
Documentation Source Repo Host	gerrit.onap.org	gerrit.openfv.org	All documentation is on the wiki.onap.org as pages or attached reference documents in PDF form. Wiki contains more than release documentation	github.org also could be sourced by gerrit or other git tools Maybe we could create a onap.github.org
Documentation Source Repo Structure	/docs - Top level documentation index & select cross project content /<any other project repo>/docs - documentation source created/maintained by a project that is integrated into the top level index and documentation for release sub-directories of both of the above reflect the documentation index hierarchy	Top Level Example of one "other project" Top level structure (sub-directories) include templates, release, development, testing. Example other project provides (in sub-directories) material for integration into "release" and "development"	Subset of the links on wiki.onap.org eg. Using ONAP	Same
Source Format	Restructured Text Comments (@gg2147@att.com) Pros More Features (e.g. footnotes, tables, citations, tables of contents) Standardized & Uniform spec Fully extensible Good for more robust documentation Cons Complexity = tougher to enforce adoption and consistency with developers? (Comment: @Matthew Harffy - I think the structure is actually there to make it more consistent and enforcable) Comments on editing tools: (@Matthew Harffy) Some example editors here: https://wiki.typo3.org/Editors_(reST) I have looked at http://rst.ninjs.org/ - it is simple, but validates semantics on the fly and makes for quick editing. As an online tool, I could see issues with not having the content stored in a repository at the editing stage, or on a local machine. The comments on https://notex.ch/ seem very positive, but I can't access it.	Top Level Index Page	Multiple Requiring Commercial Software	Markdown Comments (@gg2147@att.com) Pros Well-known by Developers (e.g. Github / Stackoverflow) Easy to learn, fewer features Simplicity = easier to enforce consistency with developers? (Comment: @Matthew Harffy - the simplicity could be a considered a con, as it makes it more difficult to enforce structure and consistency.) Good for html on a single page (e.g. blogs, github descriptions, comment boards, etc.) Cons Basic features may not be adequate for large scale projects Not extensible, multiple "flavors" of Markdown in marketplace No Semantic meaning - requires embedded HTML markup
Published Documentation	HTML, PDF, Epub for all documentation at onap.readthedocs.io/en/latest/	http://opnfv.readthedocs.io/en/latest/	HTML or PDF depending on the document or topic	HTML at github.org(no need to build) other documentation by jekyll.
CI/CD Flow	Committer approved change merged to doc or other project/doc repository branch triggers a verify & build of published documentation.	Top level index reference to other project release notes and creation of a composite source document set	Manually updated for a release by collecting information from projects eg. Release Notes 1.0.0 draft	For Markdown. Committer approved change merged to doc or other project/doc repository branch, no building progres, the webpage will be refreshed in seconds For PDF or other form, same with RST.
CI/CD Tools	Gerrit, Jira, Tox, Jenkins, Sphinx			Gerrit,Jira, Jekyll. No need any CI tools, just use the github.org to gerenrate a webpage.

Option Summary	Option 1	Option 2

Option Summary	Option 1	Option 2
Language	ReStructured Text	Markdown

Site Generator	Sphinx	Jekyll
Publish	ReadTheDocs	GitHub

Comparison for more Opensource Documentation Projects

Company Name	Document Project	Project Type	Open Source License	Document Library Management	SCM	Develop Language	Language Style	Review	Bug Tracking	Compile Tool	Translation Process	Release Method	CI Tool	Release Cycle	Release Form	Other Supporting Tools	Search Implementation

Company Name	Document Project	Project Type	Open Source License	Document Library Management	SCM	Develop Language	Language Style	Review	Bug Tracking	Compile Tool	Translation Process	Release Method	CI Tool	Release Cycle	Release Form	Other Supporting Tools	Search Implementation
NASA And Rackspace	openstack	Open source project	Apache 2.0	Open library	Git	rst	--	PR/Review meeting/Docking internal bug tracking system	issues/JIRA	Sphinx	Independent branch	Offline CI	www-generator.py publishdocs.sh	Released with product release	Website/pdf	R & D document generation tool?contains terminology tools?	?
Microsoft	Microsoft Azure	Open source project	MIT	Open library + Private library	Git/Github	Markdown	DFM	PR	PR/Labels Automation bot tracking building and Bug	DocFX	Independent branch	Offline CI	DocFX	Every day	Website	DocFX	?
Google	Google-Tensorflow	Open source project	Apache License 2.0	Open library + Private library	Git/Github	Markdown	GFM	issues	issues	Website generator+doxygen	?	Offline CI	g3doc website generator	?	Website	API automatic generation tool, gen_docs.sh, text processing tools	Borrow Google website search
	Google-Kubernetes	Open source project	Apache License 2.0 Creative Commons Attribution 4.0	Open library + Private library	Git/Github	Markdown	GFM	PR/issues	issues	Jekyll	?	Online	Jekyll	?	websites	?	?
	Google-GCP	Closed source project	?	Private library	Internal git	markdown	?	?	?	g3doc	?	Offline	?	?	website	?	?
sencha	Extjs	Closed source project	?	Private library	Git/Github	Markdown	?	?	?	JsDuck	?	Offline	?	?	website	?	?
StackExchange	Stackoverflow	Closed source project	?	?	Git/Github	Markdown	?	?	?	?	?	Online	?	?	website	?	?
Amazon	AWS	Closed source project	?	All open(only Developer guide)	Git/Github	rst	?	?	?	Sphinx	?	Offline CI	build_docs.py	?	website	?	?
Amazon	Labs126	Closed source project	?	?	Git/Github	Markdown	GFM	?	?	Jekyll	?	Offline CI	?	?	website	?	?
Docker	docker	Open source project	?	Open library + Private library	Github	Markdown	GFM	?	?	hugo	?	?	?	?	website	?	?
?
Project of document tool
Sphinx	Sphinx	Open source project	BSD	?	?	rst/markdown	?	?	?	?	?	Offline	sphinx cli	?	website/Apple Help/ePub/LaTex/text/manual page (unix)/Textinfo/linkcheck builder/c++ domain	?	?
Github	Gitbook	Open source project	Apache 2.0	?	?	md/ascii text	GFM	?	?	?	?	Offline	gitbook cli	?	website/pdf/epub/mobi	?	?
Github	Github	Closed source project	?	All open	Git/Github	?	?	PR/issues	?	Jekyll	?	Online	Jekyll	?	?	Jekyll-Auth	?

Recommendation

Based on the comparisons above, a discussion with Sofia Wallin on experience with Documentation in OPNFV, and two examples A Sample about how to develop documents by Markdown and An Example of Creating Documents with ReStructured Text-Sphinx-Readthedocs we recommend:

ReStructured Text-Sphinx-Readthedocs as the way to organize and publish ONAP documentation.
Where there are existing source documents in other formats or ReStructured Text is hard to use for new content, we will identify options to support these on a case by case basis (eg. Templates for ReStructured Text, Extensions for Sphinx, Converters, etc).