SensSoft Website + Documentation

["Gimenez, Clayton C." <cg...@draper.com>]

Hi all,

Goal of this is to kick off a discussion of how we want to build SensSoft’s main website and documentation pages, what they should include, and what our Infra needs would be to support that.

To start, a quick state of the docs:

  *   UserALE.js and UserALE docs are currently in hand-written markdown in the Readme and the gh-pages branch, which is a Jekyll-generated static site.
  *   UserALE-pyqt5 and Distill docs are auto generated by Sphinx.
  *   Tap and Stout docs are Readme and a very light Github wiki.

We want to consolidate all these various docs into a single collection as part of senssoft.incubator.apache.org.  From there, we can break down docs for each component out into its own subpage, etc.  This approach lets us keep a consistent visual style, but still have some freedom to structure and format docs in the ways that make the most sense for each component.  Technically, it breaks down into two pieces: static site generation and consolidating documentation.

For static site generation, I’d suggest Jekyll.  It has a great feature set for developing static sites and plays nicely with anything we want to do stylistically or in JavaScript to demo SensSoft or improve the site’s UX.  Pages are generated from Markdown, which means no one has to be familiar with or worry about the HTML/CSS side of things to get nicely formatted docs.

For docs consolidation, I see a few options:

  1.  Each component contributes documentation directly to the website repo.  This is easiest for the website, but means documentation is separated from code. And probably more likely to be out of date as a result.  If using inline docs (like Distill), each component would need its own process to compile into markdown or another format the static site generator can use and update the website repository.
  2.  Each component includes its own documentation, compiles it, and stores it in the repo.  The website build process would need to pull those generated files from the repo to include in its build.  We’d likely need a way to specify the current active version and associated branch for each component.
  3.  Same as #2, but the components do not compile and store their built docs.  The website build process looks at the repos and generates docs when it builds.

Personally, I think I favor option #2.  Each component can use documentation styles and tools appropriate to its language/domain (esp. with respect to inline documentation).  As long as they compile to a consistent format and folder structure, the website build system can parse and include them in a unified experience.

As far as Infra is concerned, Jekyll + Option 2 would only require static web hosting.  All the complex stuff would be preprocessing on the website developer’s machine.  In theory, it could be automated with something like Jenkins to make the site autoupdate on component documentation change.

Thoughts?

Thanks,
Clay


P.S. @Lewis: One question for you specifically — reviewing http://incubator.apache.org/guides/sites.html and some Apache project repos, it looks like the project’s website source is typically kept in the project’s main repo.  We don’t really have one of those.  Do you know of any prior projects with a similar issue?  Do you think it makes sense to spin up a new repo, say incubator-senssoft.git, for top-level project concerns like the website, full system deployment tools, etc.?

________________________________
Notice: This email and any attachments may contain proprietary (Draper non-public) and/or export-controlled information of Draper. If you are not the intended recipient of this email, please immediately notify the sender by replying to this email and immediately destroy all copies of this email.
________________________________