[Proposal] Change the format of the site to readthedocs.

[wmarshall484]

I propose changing the look and feel of the streamsx.documentation website to the readthedocs theme. Readthedocs is a fairly standard format for repositories of documentation, and is used by many projects including:

• Mozilla
• IBM IoTF
• Tensorflow
• Tweepy
• Twilio

I believe the new theme would make our new website more navigable, and improve the overall look and feel, while also simplifying the process of pushing changes to the git repository through the use of mkdocs).

I've created a preview of what our documentation site would look like after the change, which can be found here.

Pros:

• In my opinion, the scrolling table of contents sidebar is an improvement over the current top-level table of contents:
  
  The readthedocs's table of contents never goes away, so the user isn't forced to hit the back button to return to navigation.
• The code syntax highlighting supports side-scrolling, fenced code blocks, and has github's style of highlighting:
  
• The readthedocs theme is generated by the mkdocs tool, which is easier to use and install than windows. Features include:
  • Automatically deploy changes to github using mkdocs gh-deploy
  • Separation of master and gh-pages branches (markdown files are on master, html on gh-pages)
  • Easy to change the theme if needed

Cons

• Some of our custom html no longer works, including:
  • Code tabs
  • Warning and notices
  • The "click-to-show youtube video" functionality.
• The table of contents only supports one level of nested directories, so samples like the nifty fifty need to be put on one page.
• We'll have to recreate the "edit on github" button, as it isn't supported by default with mkdocs.

Despite the cons, I think using readthedocs and mkdocs improce on the existing design and workflow. If there's interest, I can create a wiki document describing the steps to take to get started. Thoughts?

New site preview.

[chanskw]

+1 thank you @wmarshall484! I like the new look and feel, and agree with you that we need to improve on the navigation bar and general workflow.

I only concern I have is the mkdocs license, which is a BSD license. I have to check if we are allowed to use that.

Let's start a wiki document to discuss the details and figure out what it takes to use mkdocs. I really like this idea. Thank you!

[wmarshall484]

the mkdocs license, which is a BSD license.

Since we're just using the tool, and not redistributing it/bundling it, I wonder if that's an issue since we're only putting the generated html on the website.

[ddebrunner]

+1

[natashadsilva]

@wmarshall484 @chanskw any updates on the BSD license issue?