Comparison for current Tools
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 | 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 & /<any other project repo>/docs - documentation sub-directories of both of the above reflect the |
| Subset of the links on wiki.onap.org | Same |
Source Format | Comments (Gregory Glover) Pros
Cons
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 | Comments (Gregory Glover) Pros
Cons
|
Published Documentation | HTML, PDF, Epub for all documentation at onap.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 |
---|---|---|
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 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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-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 | ? | ? |
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 | 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).
5 Comments
Spencer Seidel
I'm a developer/technical writer who worked on the DCAE team within AT&T last year. I redesigned a documentation system that produces the DCAE Deployment Guide that we're hoping to open source soon. The team faced several challenges that the documentation system – tentatively called "MkTechDocs" – solved.
MkTechDocs is 100% open source. It's standardized around GNU Make, Markdown (because most developers already know it), and pandoc. At its heart is a small set of document transformation pandoc "filters," which manipulate pandoc AST in order to maintain consistent heading levels across multiple markdown documents, fix internal document links, allow for infinite recursive includes, syntax highlighting, UML diagrams (via PlantUML). It could also fit nicely into a CI toolchain since builds can be triggered.
We're hoping to release it as open source soon, at which time the documentation (created with the system, naturally) will be available to check out.
I think it might be worth considering given that it's been used now by the DCAE team for a year or so.
Liu Yang
Hi Spencer, I am James, also a TW from huawei. I am very exciaty that you'v shared your experience to us. If I don'e misunderstand, you have design a documentation system basic on MD file, right?
My team study MD as a basic documentation developing tools since last year, and the story happens to us as your team. Now we make very big step on Conversion and styles. Like you have down, we increased the ability of jekyll and MD. Actualy I need to have a conversation with you to share the fuctions we've done and the more useful feature to be done.
BTW, I am the guy who made the comparison for those tables above.
Spencer Seidel
Hi James --
Yes, MkTechDocs uses Markdown. However, the system is flexible enough that it can use other formatting syntax that pandoc can understand. What's interesting is that using my system, a team who has already standardized on Textile, for example, could use that if they wanted. It was designed from the ground up to be as flexible as possible since we thought that was the best way to encourage busy developers to actually document their code , by making it super easy to do so. Then, we technical writers can edit and proof it for consistency and grammar, etc.
I have also worked with another team at AT&T for a while, RCloud, who also uses Markdown and make. I have concluded that many people use a similar technique to build their documentation. The difference with my system is that I've completely abstracted the build system away from the project so that it is easily distributed. I.e. it is project agnostic and easily configured for basic setups.
I will post a link to the repo whenever it goes public.
Spence
Michael Hwang
I'm a developer on the DCAE team and for the DCAE platform documentation, we used Mkdocs and published on Github pages. Good documentation is very important but is always been a hassle for developers to maintain and keep up-to-date. Keeping the documentation easy by using tools that developers are already familiar with is important to lower the obstacle. For me Mkdocs provided the best, easiest experience compared to Hugo and to Jekyll particularly the integration with Github pages. Mkdocs focus is on building documentation websites unlike Jekyll and Hugo.
I would also advocate for Sphinx and rst because of its wide adoption with the Python community and because of its focus on building documentation sites.
Sandeep Shah
What is the recommendation for Restructured text editor? Thank you.