Versions Compared

Old Version 1

changes.mady.by.user Rich Bennett

Saved on

compared with

New Version Current

changes.mady.by.user Rich Bennett

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Comparison for current Tools

CharacteristicProposed for ONAPExample from OPNFVCurrent ONAP & ExamplesOther Option or Examples
Documentation Source Repo Hostgerrit.onap.orggerrit.openfv.orgAll 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

/

doc

docs - Top level documentation index &
          select cross project content

/<any other project repo>/

doc

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 PageMultiple 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 DocumentationHTML, 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 FlowCommitter 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 ToolsGerrit, Jira, Tox, Jenkins, Sphinx

Gerrit,Jira,

Jekyll.

No need any CI tools, just use the github.org to gerenrate a webpage.

Option SummaryOption 1Option 2
LanguageReStructured TextMarkdown



Site GeneratorSphinxJekyll
PublishReadTheDocsGitHub

Comparison for more Opensource Documentation Projects

Company   NameDocument ProjectProject TypeOpen Source LicenseDocument Library   ManagementSCMDevelop LanguageLanguage Style
   		ReviewBug TrackingCompile ToolTranslation ProcessRelease MethodCI ToolRelease CycleRelease FormOther Supporting ToolsSearch Implementation
NASA   And RackspaceopenstackOpen source projectApache 2.0Open libraryGitrst--PR/Review   meeting/Docking internal bug tracking systemissues/JIRASphinxIndependent branchOffline CIwww-generator.py
    publishdocs.sh		Released with product   releaseWebsite/pdf    R & D document generation tool?contains terminology tools?
   		?
MicrosoftMicrosoft AzureOpen source projectMITOpen library +   Private libraryGit/GithubMarkdownDFMPRPR/Labels
    Automation bot tracking building and Bug		DocFXIndependent branchOffline CIDocFXEvery dayWebsiteDocFX?
GoogleGoogle-TensorflowOpen source projectApache License 2.0Open library + Private   libraryGit/GithubMarkdownGFMissuesissuesWebsite   generator+doxygen?Offline CIg3doc
    website generator		?WebsiteAPI automatic   generation tool, gen_docs.sh, text processing toolsBorrow Google website   search
Google-KubernetesOpen source projectApache License 2.0
    Creative Commons Attribution 4.0		Open library +   Private libraryGit/GithubMarkdownGFMPR/issuesissuesJekyll?OnlineJekyll?websites??
Google-GCPClosed source project?Private libraryInternal gitmarkdown???g3doc?Offline??website??
senchaExtjsClosed source project?Private   libraryGit/GithubMarkdown???JsDuck?Offline??website??
StackExchangeStackoverflowClosed source project??Git/GithubMarkdown?????Online??website??
AmazonAWSClosed source project?All open(only   Developer guide)Git/Githubrst???Sphinx?Offline CI

Recommendation

...

build_docs.py?website??
Labs126Closed source project??Git/GithubMarkdownGFM??Jekyll?Offline CI??website??
DockerdockerOpen source project?Open library +   Private libraryGithubMarkdownGFM??hugo????website??
?
Project of document tool
SphinxSphinxOpen   source projectBSD??rst/markdown?????Offlinesphinx cli?website/Apple Help/ePub/LaTex/text/manual page   (unix)/Textinfo/linkcheck builder/c++ domain??
GithubGitbookOpen source projectApache 2.0??md/ascii textGFM????Offlinegitbook cli?website/pdf/epub/mobi??
GithubClosed   source project?All openGit/Github??PR/issues?Jekyll?OnlineJekyll??Jekyll-Auth?


Anchor
recommendation
recommendation
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).