SensSoft Website + Documentation

[Gimenez, Clayton C.]

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.

Re: Access to apache.github repos to add github.io pages [SENSSOFT]

[Gimenez, Clayton C.]

Hi Lewis,

Totally agree re: documentation approach.  Just chimed in to clarify the 
permissions question.

I’ve been looking into Apache’s website docs and a few deployment strategies 
and will kick off a new dev@senssoft.i.a.o thread to bounce around shortly.

Thanks,
Clay

From: "Mcgibbney, Lewis J (398M)" 
>
Date: Wednesday, October 5, 2016 at 1:41 PM
To: "Clayton C. Gimenez" >
Cc: 
"dev@senssoft.incubator.apache.org" 
>
Subject: Re: Access to apache.github repos to add github.io pages [SENSSOFT]

Hi Clay,
Infra to Bcc
Ideally we would host everything under senssoft.incubator.apahe.org (which is 
hosted at the ASF) as oppose to Github docs.
The reason that no configuration exists for Github docs is that we want all 
websites to follow the same convention e.g. ${podling}.incubator.apache.org or 
${top_level_project}.apache.org.
So the question I am going back to here is that we need to

1)   Aggregate and consolidate all of the existing documentation

2)   Decide on our preferred deployment strategy which would follow the 
hosting mechanisms available @Apache

3)   Then approach infra and ask them to set us up with whatever 
infrastructure we require.
How does this sound? Can we take this over to 
dev@senssoft.i.a.o?
Thanks folks
Lewis

Dr. Lewis John McGibbney Ph.D., B.Sc.
Data Scientist II
Computer Science for Data Intensive Applications Group 398M
Jet Propulsion Laboratory
California Institute of Technology
4800 Oak Grove Drive
Pasadena, California 91109-8099
Mail Stop : 158-256C
Tel:  (+1) (818)-393-7402
Cell: (+1) (626)-487-3476
Fax:  (+1) (818)-393-1190
Email: lewis.j.mcgibb...@jpl.nasa.gov

   [cid:image001.png@01D21EF5.0B160920]

 Dare Mighty Things

From: "Gimenez, Clayton C." >
Date: Wednesday, October 5, 2016 at 7:54 AM
To: "gst...@gmail.com" 
>
Cc: "Poore, Joshua C." >, 
"infrastruct...@apache.org" 
>, "Mcgibbney, 
Lewis J (398M)" 
>, 
"Mattmann, Chris A (3980)" 
>, 
"dev@senssoft.incubator.apache.org" 
>
Subject: Re: Access to apache.github repos to add github.io pages [SENSSOFT]

At least in the case of Userale.js, the Github Pages files are already in the 
Apache repos at git-wip.a.o, and are mirrored to 
github.com/apache/incubator-senssoft-useralejs.  To have those pages be live, 
served by Github Pages at apache.github.io/incubator-senssoft-useralejs, a 
setting needs to be flipped in Github, which someone with admin rights to the 
Apache Github org would need to do.  Specifically, Settings -> Options -> 
Github Pages -> (Turn it on).  There might be organization-level settings that 
would need to be changed, but I¹m not sure.

In the end, all the documentation will be moved to the main SensSoft webpage, 
but this would allow us to keep our existing documentation live and attached to 
Apache in the interim, if it’s an option.

Clay


-Original Message-
From: Greg Stein [mailto:gst...@gmail.com]
Sent: Tuesday, October 04, 2016 5:45 PM
To: Poore, Joshua C. >
Cc: infrastruct...@apache.org; Mcgibbney, 
Lewis J (398M)
>; 
Mattmann, Chris A (3980)
>; 
dev@senssoft.incubator.apache.org
Subject: Re: Access to apache.github repos to add github.io pages
[SENSSOFT]

Hi Joshua,

What is it that you need from Infra? What is different from the
senssoft community just committing/pushing all those pages into git-wip.a.o?

I'm not sure where "permission" lands in there.

Thanks,
-g


On Tue, Oct 4, 2016 at 3:07 PM, Poore, Joshua C. 
>
wrote:

Hello‹



We¹re incubating at Apache. We¹d like to move our github.io docs
pages  from our old repos to our apache.github mirrors to consolidate
documentation. How best/who best to ask for permissions to stand these
up?
Ideally, we¹d like to generate sphinx templates for all Apache
SensSoft documentation that would live in these repos.



Repos can be found here: https://github.com/apache?
utf8=%E2%9C%93=senssoft





Thanks!



Josh



Joshua 

RE: Access to apache.github repos to add github.io pages [SENSSOFT]

[Poore, Joshua C.]

@Lewis

I think my team was operating under some different assumptions regarding our 
ability to push our github docs pages that are currently posted on 
Draperlaboratory/github to apache. I'll round up with them RE Greg's email. I 
think we all have consensus on the effect we want, but maybe some disconnects 
in how we think we can get it done.

For clarity's sake, here is the schema of how our websites/documentation will 
be managed.

Corporate Branding of SensSoft: softwareasasensor.com redirects to 
draper.com/softwareasasensor (note that we will still be compliant with Apache 
marketing and branding rules regarding incubator projects). This page will of 
course link to Apache community and repos.

Apache Community: incubator.apache.org/projects/sensoft.html will be our home 
page for our Apache projects, this will connect to vm requested (INFRA-12671) 
and host demos. Links to documentation redirect to git.io pages, which we are 
trying to build on Apache git resources (currently built on 
draperlaboratory/git repos). If we can just push these into git-wip.a.o as Greg 
suggests, then that problem is solved.

More soon...

-Original Message-
From: lewis john mcgibbney [mailto:lewi...@apache.org]
Sent: Tuesday, October 04, 2016 5:57 PM
To: dev@senssoft.incubator.apache.org
Subject: Re: Access to apache.github repos to add github.io pages [SENSSOFT]

@Josh,

On Tue, Oct 4, 2016 at 1:24 PM, <
dev-digest-h...@senssoft.incubator.apache.org> wrote:

>
> From: "Poore, Joshua C." 
> To: "infrastruct...@apache.org" 
> Cc: "Mcgibbney, Lewis J (398M)" ,
> "Mattmann, Chris A (3980)" , "
> dev@senssoft.incubator.apache.org" 
> Date: Tue, 04 Oct 2016 20:07:42 +
> Subject: Access to apache.github repos to add github.io pages
> [SENSSOFT]
> Hello-
>
> We're incubating at Apache. We'd like to move our github.io docs pages
> from our old repos to our apache.github mirrors to consolidate
> documentation. How best/who best to ask for permissions to stand these up?
> Ideally, we'd like to generate sphinx templates for all Apache
> SensSoft documentation that would live in these repos.
>

This was previously open over on
https://issues.apache.org/jira/browse/INFRA-12264
Essentially if we can decide on a strategy then we can open a ticket within the 
INFRA Jira ticket and request resources there.
As Greg has mentioned, we can do most of this ourselves.
Would you want INFRA to create a new, separate Git-based repository at 
something like 
https://git-wip-us.apache.org/repos/asf/incubator-senssoft-website.git ?
We could then create all documentation in sphinx, build it locally and push the 
docs to the Website for deployment. Honestly to me it doesn't matter but it 
would be good to get some consensus.
 Lewis

 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.