How to handle the documentation access from readium.github.io about architecture HOT 13 CLOSED

apparently the Jekyll build scripts can be invoked automatically from a continuous integration server following a commit+push on any branch (which can be filtered via a whitelist based on a syntactical convention, or just a complete branch name):
https://jekyllrb.com/docs/continuous-integration/travis-ci/

from architecture.

IMHO the second solution is much better, since it's much more dynamic and the work required (adding front matters to the docs) is minimal.
The only burden is the copy of the jekyll config in the readium-2 space: low burden since it won't change in the medium term.

from architecture.

We don't even have to move to a gh-pages branch, we just need to update the repo settings to use the master branch for github pages.

from architecture.

What I'm really wondering about is mostly timing.
We're still in the early days of handling all of this documentation and we're likely to iterate over this repo for some time.

IMO rolling out an HTML version only makes sense when we're a little bit more stable than that.

from architecture.

Also, there's one thing that I haven't seen mentioned here: should the Readium-2 docs remain separate from the rest of the Readium docs already generated using Jekyll?

We could only publish documents that we're confident about in readium/readium.github.io using remote_include and this mechanism could also be useful for maintaining the LCP spec.

from architecture.

It's possible using the solution 2, by not putting front-matters in the documents we don't want to publicly expose.

from architecture.

That's true, but in that case I'd like to see consistency across all repos dedicated to documentation (LCP and Web Publication Manifest too).

As for the pros and cons, I have mixed feelings.
For a specification document (Web Publication Manifest or LCP) having to manually touch a document to trigger a regeneration is a feature, not a bug IMO. I see the additional step as a safety net to avoid versions that we don't want to get published.

from architecture.

In the Github spirit, I would therefore treat the LCP spec using a develop branch (moving) and a master branch which contains the tagged revisions. Only the master branch would be seeable as html doc (thanks to its jekyll front matter).

from architecture.

I'm not a big fan for documents because it means lower visibility, which is the opposite of what we want (we need as many eyes as possible to review a draft).

I like the W3C approach better where you have both the current draft and "publishing snapshots" in the same branch: https://github.com/w3c/dpub-pwp

from architecture.

Can Jekyll "rendering" be manually triggered for a release tag on the master branch (for official stable documentation updates), as well as automatically triggered (continuous integration) for editors drafts?
What URL / domain would be used for stable docs vs. living documents?
e.g.
https://readium.org/lcp/specs/1.0
vs.
https://readium.org/lcp/specs/draft

from architecture.

@danielweck I don't think so. Jekyll is triggered by a modification on a file in the selected branch (gh-pages or master). It's a basic mechanism.

from architecture.

Now that Ric intends to move readium.org and epubzone to githib/jekyll, it would be good to be able to close this issue.

The gh-pages solution works, but imposes a copy of the jekyll readium templates in the r2 repo, which may make maintenance more difficult for these templates.

The best conclusion therefore seems to be using the first solution (the ad-hoc "include-remote" script) for R2 including selected architecture texts in readium.org.

I'll close this issue after validation in a R2 call.

from architecture.

In fact in https://help.github.com/articles/adding-jekyll-plugins-to-a-github-pages-site/ I discover that plugin like the one we tried to import external md pages (from the readium-2 repo) to the readium.org webpages are not allowed by github (for security reasons), i.e. they work locally (when using bundle exec jekyll serve) but not when github itself is the engine (the solution is to copy to github the "resolved" site, which is not what we want). We were able to commit on the develop branch with no issue, but it gives an error when merged in the master branch.

We currently want to pick and choose some pages from the readium-2 repo and have them accessible on the readium.org website: the best solution I see for the short term is a copy of the .md content.
I'll do it now, so the readium.github.io website can be up to date.

from architecture.