Re: [DISCUSS] GRAV - flat file CMS

[Jamal Natour <ja...@miracl.com>]

Please, please - plain html5/css and jquery.

It's just a doc website, and we really should not overcomplicate matters.

If we need specific functionalitity, we should have a business case for it,
otherwise YAGNI.

my 2p
jamal



On Wed, Apr 6, 2016 at 11:34 AM, Tomasz Matecki <to...@miracl.com>
wrote:

> Welcome all,
>
> While the project Milagro Apache (incubating) is going to be announced and
> introduce to Apache community in beginning of May we are about to create
> new website - the place for all our community activities and main POC with
> our prospect users.
> That is why it is extremely important to have it clear, understandable,
> and even more important - easy to access and edit if needed.
>
> Having that in mind I want to raise a discussion here about using a GRAV
> https://getgrav.org
> This is flat file CMS, with no backend database to support.
>
> We are thinking of using GRAV in terms of both - website itself and
> documentation pages.
>
> While it is not a standard for for incubator project and not even for
> graduated Apache projects - if we want to use it we need to ask the
> infrastructure team to support the Milagro website being hosted on an
> Apache Web Server using an open source flat file CMS - GRAV.
>
> Please can you place your comments or thoughts here.
> I want to encourage everyone on this list to use this form of
> communication and discussion more often and more actively - as this is a
> best practice and standard tool for projects under ASF
>
> I know that for most of us it is first project under Apache - so let’s try
> to work in Apache way
>
> *And finally I’d like to remind the MILAGRO is currently in INCUBATION
> stage -  so that mean we CAN NOT use “Apache Milagro” statement in any
> communication, so please have this in mind.*
> *Variants like "Apache Milagro (incubating)", or "The Milagro project,
> currently in incubation at Apache” are fine - so please use those instead. *
>
> Regards
> Tomasz Matecki
>
>
>
>

Re: [DISCUSS] GRAV - flat file CMS

[Brian Spector <br...@miracl.com>]

Hi Anthony,

Let me be more clear: we haven't had good luck with the Latex capability in
Sphinx which is what RTD uses.

See the attached paper written in Latex and then output to PDF or this link
for a view of what we are talking about:

http://www.mit.edu/~wsshin/jemdoc+mathjax.html

Half the time equations render...strangely.. when transformed during the
Sphinx build and the final is shown in a web page, which is what RTD uses.

It's important that cryptographers can read this stuff, in a web page. Not
having properly rendered equations is not an option. MathJax is great.
Works. Grav has a plugin for this.

Additionally, the points I made below are still top of mind.

In any case, it's easy to use MathJax with a static site generator, that's
not an issue per se it just the tooling would be easier with what we have
setup and we are under a deadline with Apache Con.

I think your list is good but I would like to do a parallel track.

Let's ask the infrastructure team about 4. What's the worst they could say?
no?

And then let's start on number 2 straight away so we can get the docs
looking awesome in time for Apache Con.

As long as the assets are accounted for the scraping of HTML to push into
the ASF SVN shouldn't be that hard.

I've searched high and low for a communications channel to the
infrastructure team.

Could be jet lag but how do we get in touch with them?

Thanks.

>> >> Fourth, Grav has an extensive set of plugins and tooling that can
>> enable a
>> >> richer experience above and beyond just a flat file CMS site. Without
>> going
>> >> into laborious detail, we would like to have a discussion forum,
>> automated
>> >> form to auto-enrol folks into the Milagro Slack (our not having this
has
>> >> come up more than once already) and the ability to showcase some of
the
>> >> technologies that Milagro Project (incubating) has that are relevant
to
>> web
>> >> apps and mobile authentication.
>> >>
>> >> Namely, these are Milagro MFA (multi-factor authentication) using the
>> M-Pin
>> >> Protocol. In short, we would like to be able to show this in the
Milagro
>> >> site. Here's the Pin Pad version, here is the headless version, etc.
>> Makes
>> >> sense, right?  While this certainly can be done in pure JavaScript,
PHP
>> is
>> >> still the dominant language found on most production web sites, even
>> today.
>> >> Being able to inspect that code in the repo and have it demonstrable
in
>> the
>> >> Milagro site itself makes the technology "real" in our view.



On Wed, Apr 6, 2016 at 10:54 PM, anthony shaw <an...@gmail.com>
wrote:

> Both Apache CloudStack -
> http://cloudstack-release-notes.readthedocs.org/en/4.8.0/ and Apache
> Libcloud http://libcloud.readthedocs.org/ use RTD, there are probably
> others.
>
> I listened to an interview with the RTD creator the other week, they
> need some adverts to fund the engineers to operate the service.
>
> It is also open-source, so if you wanted to run your own you can quite
> easily.
>
> I'm a big fan of anything that doesn't require additional maintenance,
> time and/or infrastructure from the community, since most of us are
> volunteers.
>
> I work on the libcloud website, that's written using a static page
> generator, we write markdown and then.
> The docs are build dynamically from RTD and linked to from the main
> website http://libcloud.apache.org/
>
> The advantage is that you can use the site generator within the
> existing SVN -> Web infrastructure that the core apache team maintain.
>
> It sounds to me that choices are:
> 1) RTD for docs and a static website
> 2) We (maintainers) all install GRAV locally and as part of a release
> process regenerate the GRAV site and publish the HTML into the ASF SVN
> repo, this puts no additional requirement on the infra team, you get
> to use GRAV but the content on the website is relevant to the released
> version (which might be beneficial anyway) - don't forget that you
> need to manually vote on a release anyway and generate release
> artifacts so having to update the docs is a minor task in the process
> 3) Combination of 1 and 2.
> 4) ask for the infra team to get GRAV on the servers
>
> FWIW, I think 3 keeps everyone happy and doesn't introduce any
> blockers to progress.
>
> Anthony
>
>
>
> On Thu, Apr 7, 2016 at 3:16 PM, Brian Spector <br...@miracl.com>
> wrote:
> > Hi Anthony,
> >
> > This whole discussion was actually about all of the project website,
> > including tech docs, on Grav for the reasons I outlined below.
> >
> > As far as readthedocs goes, we like readthedocs.org and know of it.
> >
> > However, it is turning into a commercial / paid for service.
> >
> > See: https://docs.readthedocs.org/en/latest/business/index.html
> >
> > We weren't really sure how the community would feel about the docs site
> > being hosted there?
> >
> > As an aside, if no one minds readthedocs.org hosting the project's
> > documentation then certainly one of the main project contributors paying
> a
> > few bucks a month at Heroku or Dreamiest can't be all that controversial
> > either for at least the documentation and maybe demo side of things?
> >
> > The other bit was that when we have run Sphinx and MKDocs in the past the
> > notation in Latex was really a bear to get to build out properly. Not
> sure
> > if that's changed but since we have a ton of math (being crypto) to
> > document, we have had good success with MathJax, and Grav has a plugin
> for
> > it:
> > https://github.com/sommerregen/grav-plugin-mathjax
> >
> > Because Grav is just a flat file CMS you can get a deployment system
> going
> > using git hooks as well, with just a bit more work:
> > http://hibbittsdesign.org/blog/posts/2015-12-11-using-grav-with-github
> >
> > Grav website content is written in Markdown. So that makes it easy to
> > modify, merge, write, etc and we can manage the content through version
> > control.
> >
> > Are other projects using readthedocs?
> >
> > We could just keep the main page a static file and link to docs and demos
> > from the main page?
> >
> >
> >
> > On Wed, Apr 6, 2016 at 8:38 PM, anthony shaw <an...@gmail.com>
> > wrote:
> >
> >> Hey,
> >>
> >> Why not just use https://readthedocs.org/
> >>
> >> Point it at the Git repo, it'll compile, construct, publish and host
> >> the documentation for you as well as build the docs automatically
> >> after every commit using git hooks. Supports Markdown and Restructured
> >> Text
> >>
> >> It's becoming the new standard in the Python world for doc hosting.
> >>
> >> Plus its free!
> >>
> >> On Thu, Apr 7, 2016 at 4:13 AM, Jamal Natour <ja...@miracl.com>
> >> wrote:
> >> > Okay that makes sense.
> >> >
> >> >
> >> > On Wed, Apr 6, 2016 at 6:46 PM, Brian Spector <
> brian.spector@miracl.com>
> >> > wrote:
> >> >
> >> >> Grav was put forward by the MIRACL team because of several reasons.
> >> >>
> >> >> First, writing in JSON for any kind of technical documentation is
> not a
> >> low
> >> >> barrier to entry. Markdown is the proper way to do this to
> democratise
> >> the
> >> >> process. Actually Markdown and Latex, which is converted via MathJax
> dto
> >> >> nice cryptographic notation, which Grav supports. Keep in mind that a
> >> lot
> >> >> of the lower level docs and functionality needs to be written not by
> >> folks
> >> >> who understand JSON but are academic cryptographers who have already
> >> >> written their information in Latex. In our experience, doing this
> >> >> conversion via a static website generator such as Jekyll has produced
> >> >> spotty results.
> >> >>
> >> >> Second, again, Grav IS A FLAT REPO. It's flat file CMS. It's
> >> requirements
> >> >> are just a web server with PHP and two mod modules. You can see the
> >> >> requirements here: http://learn.getgrav.org/basics/requirements
> >> >> This isn't like we have asked to host Wordpress or some bloated
> >> monstrosity
> >> >> (sorry Wordpress lovers).
> >> >>
> >> >> Third, because it is flat we can do versioning control on the
> Markdown
> >> docs
> >> >> via Git or other version control system just as Jamal has suggested.
> >> That
> >> >> IS our intention. Whether that fits within the Apache Way or not, I'm
> >> not
> >> >> sure, but we want to make sure that the text information on the
> website
> >> can
> >> >> managed via a common developer utilised version control system, and
> Git
> >> >> would be our preference (actually GitHub). So clone the repo, make
> >> changes,
> >> >> make a pull request, etc. to merge your changes on the Markdown docs,
> >> which
> >> >> are the foundation of the website. So this ins't for just the
> technical
> >> >> docs, this is for the entire Milagro web site.
> >> >>
> >> >> Fourth, Grav has an extensive set of plugins and tooling that can
> >> enable a
> >> >> richer experience above and beyond just a flat file CMS site. Without
> >> going
> >> >> into laborious detail, we would like to have a discussion forum,
> >> automated
> >> >> form to auto-enrol folks into the Milagro Slack (our not having this
> has
> >> >> come up more than once already) and the ability to showcase some of
> the
> >> >> technologies that Milagro Project (incubating) has that are relevant
> to
> >> web
> >> >> apps and mobile authentication.
> >> >>
> >> >> Namely, these are Milagro MFA (multi-factor authentication) using the
> >> M-Pin
> >> >> Protocol. In short, we would like to be able to show this in the
> Milagro
> >> >> site. Here's the Pin Pad version, here is the headless version, etc.
> >> Makes
> >> >> sense, right?  While this certainly can be done in pure JavaScript,
> PHP
> >> is
> >> >> still the dominant language found on most production web sites, even
> >> today.
> >> >> Being able to inspect that code in the repo and have it demonstrable
> in
> >> the
> >> >> Milagro site itself makes the technology "real" in our view.
> >> >>
> >> >> @Nick Kew, hopefully this makes sense to you to carry the request to
> the
> >> >> infrastructure team? Not sure how we thought we were going to get
> their
> >> >> attention on the dev milagro list in the first place but smarter
> folks
> >> than
> >> >> me hopefully have worked this out.
> >> >>
> >> >> How do we get an answer from the infrastructure team on this?
> >> >>
> >> >> To reiterate, the question is:
> >> >>
> >> >> Will they host Grav, which is a flat file CMS, for the Milagro site?
> The
> >> >> requirements are listed here:
> >> >> http://learn.getgrav.org/basics/requirements
> >> >>
> >> >>
> >> >> On Wed, Apr 6, 2016 at 5:44 PM, Jamal Natour <
> jamal.natour@miracl.com>
> >> >> wrote:
> >> >>
> >> >> >  > > Is that a matter of familiarity and/or legacy?
> >> >> > > > Are there existing docs managed by grav that want importing?
> >> >> > AFAIK there are no legacy requirements, and we want to be as open
> and
> >> >> > transparent a community as possible.
> >> >> > I'd really like this to be here is everything in a flat repo, so
> any
> >> >> > external contributors are as empowered to make changes as a Miracl
> >> staff
> >> >> > member.
> >> >> > We already do public development, with pull requests as our
> internal
> >> >> > workflow,  and I think that us publishing JSON for content and HTML
> >> for
> >> >> > layout from a public git repo is a fairly low bar to entry.
> >> >> >
> >> >> > I'm a little uncomfortable with us *needing* more than that for
> >> >> > documentation, as it suggest some business process is being
> delegated
> >> to
> >> >> > tooling.
> >> >> > If we have business needs to accommodate, we should split this off
> >> into a
> >> >> > possibly internal discussion on how *PE* and *DEVOPS* can best
> support
> >> >> > these needs.
> >> >> >
> >> >> > Otherwise, I'd prefer that docs are stored alongside code in git,
> and
> >> are
> >> >> > handled like code.
> >> >> > I'd would like to avoid any  "in-house only" magic to produce docs
> >> >> > especially where we must engage with people who cannot use such
> visual
> >> >> > tools due to visual impairment or other accessibility needs.
> >> >> >
> >> >> > Using a "Git first" workflow will allow us to support email, web,
> >> users
> >> >> of
> >> >> > assistive technologies, as well as a range of desktop and mobile
> >> clients.
> >> >> >
> >> >> >
> >> >> >
> >> >> >
> >> >> >
> >> >> >
> >> >> > On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <ni...@apache.org> wrote:
> >> >> >
> >> >> > > On Wed, 6 Apr 2016 14:36:49 +0300
> >> >> > > Vladislav Mitov <vl...@miracl.com> wrote:
> >> >> > >
> >> >> > > > I agree with Jamal. We can build it with some kind of static
> site
> >> >> > > > generator for convenience, but we don't need this thing on the
> >> server
> >> >> > > > for sure.
> >> >> > >
> >> >> > > Indeed.  Existing apache projects use a range of publishing
> >> >> > > models and templates.  We could certainly ping infra about
> >> >> > > using the Apache CMS if some folks would prefer, but I think
> >> >> > > they'd want a pretty compelling case to support a whole new
> >> >> > > system.
> >> >> > >
> >> >> > > The most likely trigger to adopt it would be demand coming
> >> >> > > from a range of projects.  As in, when git was introduced,
> >> >> > > or arguably even when svn replaced cvs!
> >> >> > >
> >> >> > > > > > That is why it is extremely important to have it clear,
> >> >> > > > > > understandable, and even more important - easy to access
> and
> >> edit
> >> >> > > > > > if needed.
> >> >> > >
> >> >> > > That is a problem to which many solutions are available.
> >> >> > >
> >> >> > > > > >
> >> >> > > > > > Having that in mind I want to raise a discussion here about
> >> using
> >> >> > > > > > a GRAV https://getgrav.org
> >> >> > > > > > This is flat file CMS, with no backend database to support.
> >> >> > >
> >> >> > > Is that a matter of familiarity and/or legacy?
> >> >> > > Are there existing docs managed by grav that want importing?
> >> >> > >
> >> >> > > Bear in mind that unless there's a pretty substantial legacy
> >> >> > > to deal with, committers can be expected to come from a range
> >> >> > > of different backgrounds and adapt to whatever tools are used
> >> >> > > for a particular project.
> >> >> > >
> >> >> > > --
> >> >> > > Nick Kew
> >> >> > >
> >> >> >
> >> >>
> >> >>
> >> >>
> >> >> --
> >> >> Brian Spector
> >> >> CEO
> >> >> MIRACL
> >> >>
> >> >> T: +44 (0) 20 3389 8190
> >> >> https://www.miracl.com
> >> >> 81 Rivington Street
> >> >> London UK, EC2A 3AY
> >> >> Registered in England and Wales 7017635
> >> >>
> >>
> >
> >
> >
> > --
> > Brian Spector
> > CEO
> > MIRACL
> >
> > T: +44 (0) 20 3389 8190
> > https://www.miracl.com
> > 81 Rivington Street
> > London UK, EC2A 3AY
> > Registered in England and Wales 7017635
>



-- 
Brian Spector
CEO
MIRACL

T: +44 (0) 20 3389 8190
https://www.miracl.com
81 Rivington Street
London UK, EC2A 3AY
Registered in England and Wales 7017635

Re: [DISCUSS] GRAV - flat file CMS

[anthony shaw <an...@gmail.com>]

Both Apache CloudStack -
http://cloudstack-release-notes.readthedocs.org/en/4.8.0/ and Apache
Libcloud http://libcloud.readthedocs.org/ use RTD, there are probably
others.

I listened to an interview with the RTD creator the other week, they
need some adverts to fund the engineers to operate the service.

It is also open-source, so if you wanted to run your own you can quite easily.

I'm a big fan of anything that doesn't require additional maintenance,
time and/or infrastructure from the community, since most of us are
volunteers.

I work on the libcloud website, that's written using a static page
generator, we write markdown and then.
The docs are build dynamically from RTD and linked to from the main
website http://libcloud.apache.org/

The advantage is that you can use the site generator within the
existing SVN -> Web infrastructure that the core apache team maintain.

It sounds to me that choices are:
1) RTD for docs and a static website
2) We (maintainers) all install GRAV locally and as part of a release
process regenerate the GRAV site and publish the HTML into the ASF SVN
repo, this puts no additional requirement on the infra team, you get
to use GRAV but the content on the website is relevant to the released
version (which might be beneficial anyway) - don't forget that you
need to manually vote on a release anyway and generate release
artifacts so having to update the docs is a minor task in the process
3) Combination of 1 and 2.
4) ask for the infra team to get GRAV on the servers

FWIW, I think 3 keeps everyone happy and doesn't introduce any
blockers to progress.

Anthony



On Thu, Apr 7, 2016 at 3:16 PM, Brian Spector <br...@miracl.com> wrote:
> Hi Anthony,
>
> This whole discussion was actually about all of the project website,
> including tech docs, on Grav for the reasons I outlined below.
>
> As far as readthedocs goes, we like readthedocs.org and know of it.
>
> However, it is turning into a commercial / paid for service.
>
> See: https://docs.readthedocs.org/en/latest/business/index.html
>
> We weren't really sure how the community would feel about the docs site
> being hosted there?
>
> As an aside, if no one minds readthedocs.org hosting the project's
> documentation then certainly one of the main project contributors paying a
> few bucks a month at Heroku or Dreamiest can't be all that controversial
> either for at least the documentation and maybe demo side of things?
>
> The other bit was that when we have run Sphinx and MKDocs in the past the
> notation in Latex was really a bear to get to build out properly. Not sure
> if that's changed but since we have a ton of math (being crypto) to
> document, we have had good success with MathJax, and Grav has a plugin for
> it:
> https://github.com/sommerregen/grav-plugin-mathjax
>
> Because Grav is just a flat file CMS you can get a deployment system going
> using git hooks as well, with just a bit more work:
> http://hibbittsdesign.org/blog/posts/2015-12-11-using-grav-with-github
>
> Grav website content is written in Markdown. So that makes it easy to
> modify, merge, write, etc and we can manage the content through version
> control.
>
> Are other projects using readthedocs?
>
> We could just keep the main page a static file and link to docs and demos
> from the main page?
>
>
>
> On Wed, Apr 6, 2016 at 8:38 PM, anthony shaw <an...@gmail.com>
> wrote:
>
>> Hey,
>>
>> Why not just use https://readthedocs.org/
>>
>> Point it at the Git repo, it'll compile, construct, publish and host
>> the documentation for you as well as build the docs automatically
>> after every commit using git hooks. Supports Markdown and Restructured
>> Text
>>
>> It's becoming the new standard in the Python world for doc hosting.
>>
>> Plus its free!
>>
>> On Thu, Apr 7, 2016 at 4:13 AM, Jamal Natour <ja...@miracl.com>
>> wrote:
>> > Okay that makes sense.
>> >
>> >
>> > On Wed, Apr 6, 2016 at 6:46 PM, Brian Spector <br...@miracl.com>
>> > wrote:
>> >
>> >> Grav was put forward by the MIRACL team because of several reasons.
>> >>
>> >> First, writing in JSON for any kind of technical documentation is not a
>> low
>> >> barrier to entry. Markdown is the proper way to do this to democratise
>> the
>> >> process. Actually Markdown and Latex, which is converted via MathJax dto
>> >> nice cryptographic notation, which Grav supports. Keep in mind that a
>> lot
>> >> of the lower level docs and functionality needs to be written not by
>> folks
>> >> who understand JSON but are academic cryptographers who have already
>> >> written their information in Latex. In our experience, doing this
>> >> conversion via a static website generator such as Jekyll has produced
>> >> spotty results.
>> >>
>> >> Second, again, Grav IS A FLAT REPO. It's flat file CMS. It's
>> requirements
>> >> are just a web server with PHP and two mod modules. You can see the
>> >> requirements here: http://learn.getgrav.org/basics/requirements
>> >> This isn't like we have asked to host Wordpress or some bloated
>> monstrosity
>> >> (sorry Wordpress lovers).
>> >>
>> >> Third, because it is flat we can do versioning control on the Markdown
>> docs
>> >> via Git or other version control system just as Jamal has suggested.
>> That
>> >> IS our intention. Whether that fits within the Apache Way or not, I'm
>> not
>> >> sure, but we want to make sure that the text information on the website
>> can
>> >> managed via a common developer utilised version control system, and Git
>> >> would be our preference (actually GitHub). So clone the repo, make
>> changes,
>> >> make a pull request, etc. to merge your changes on the Markdown docs,
>> which
>> >> are the foundation of the website. So this ins't for just the technical
>> >> docs, this is for the entire Milagro web site.
>> >>
>> >> Fourth, Grav has an extensive set of plugins and tooling that can
>> enable a
>> >> richer experience above and beyond just a flat file CMS site. Without
>> going
>> >> into laborious detail, we would like to have a discussion forum,
>> automated
>> >> form to auto-enrol folks into the Milagro Slack (our not having this has
>> >> come up more than once already) and the ability to showcase some of the
>> >> technologies that Milagro Project (incubating) has that are relevant to
>> web
>> >> apps and mobile authentication.
>> >>
>> >> Namely, these are Milagro MFA (multi-factor authentication) using the
>> M-Pin
>> >> Protocol. In short, we would like to be able to show this in the Milagro
>> >> site. Here's the Pin Pad version, here is the headless version, etc.
>> Makes
>> >> sense, right?  While this certainly can be done in pure JavaScript, PHP
>> is
>> >> still the dominant language found on most production web sites, even
>> today.
>> >> Being able to inspect that code in the repo and have it demonstrable in
>> the
>> >> Milagro site itself makes the technology "real" in our view.
>> >>
>> >> @Nick Kew, hopefully this makes sense to you to carry the request to the
>> >> infrastructure team? Not sure how we thought we were going to get their
>> >> attention on the dev milagro list in the first place but smarter folks
>> than
>> >> me hopefully have worked this out.
>> >>
>> >> How do we get an answer from the infrastructure team on this?
>> >>
>> >> To reiterate, the question is:
>> >>
>> >> Will they host Grav, which is a flat file CMS, for the Milagro site? The
>> >> requirements are listed here:
>> >> http://learn.getgrav.org/basics/requirements
>> >>
>> >>
>> >> On Wed, Apr 6, 2016 at 5:44 PM, Jamal Natour <ja...@miracl.com>
>> >> wrote:
>> >>
>> >> >  > > Is that a matter of familiarity and/or legacy?
>> >> > > > Are there existing docs managed by grav that want importing?
>> >> > AFAIK there are no legacy requirements, and we want to be as open and
>> >> > transparent a community as possible.
>> >> > I'd really like this to be here is everything in a flat repo, so any
>> >> > external contributors are as empowered to make changes as a Miracl
>> staff
>> >> > member.
>> >> > We already do public development, with pull requests as our internal
>> >> > workflow,  and I think that us publishing JSON for content and HTML
>> for
>> >> > layout from a public git repo is a fairly low bar to entry.
>> >> >
>> >> > I'm a little uncomfortable with us *needing* more than that for
>> >> > documentation, as it suggest some business process is being delegated
>> to
>> >> > tooling.
>> >> > If we have business needs to accommodate, we should split this off
>> into a
>> >> > possibly internal discussion on how *PE* and *DEVOPS* can best support
>> >> > these needs.
>> >> >
>> >> > Otherwise, I'd prefer that docs are stored alongside code in git, and
>> are
>> >> > handled like code.
>> >> > I'd would like to avoid any  "in-house only" magic to produce docs
>> >> > especially where we must engage with people who cannot use such visual
>> >> > tools due to visual impairment or other accessibility needs.
>> >> >
>> >> > Using a "Git first" workflow will allow us to support email, web,
>> users
>> >> of
>> >> > assistive technologies, as well as a range of desktop and mobile
>> clients.
>> >> >
>> >> >
>> >> >
>> >> >
>> >> >
>> >> >
>> >> > On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <ni...@apache.org> wrote:
>> >> >
>> >> > > On Wed, 6 Apr 2016 14:36:49 +0300
>> >> > > Vladislav Mitov <vl...@miracl.com> wrote:
>> >> > >
>> >> > > > I agree with Jamal. We can build it with some kind of static site
>> >> > > > generator for convenience, but we don't need this thing on the
>> server
>> >> > > > for sure.
>> >> > >
>> >> > > Indeed.  Existing apache projects use a range of publishing
>> >> > > models and templates.  We could certainly ping infra about
>> >> > > using the Apache CMS if some folks would prefer, but I think
>> >> > > they'd want a pretty compelling case to support a whole new
>> >> > > system.
>> >> > >
>> >> > > The most likely trigger to adopt it would be demand coming
>> >> > > from a range of projects.  As in, when git was introduced,
>> >> > > or arguably even when svn replaced cvs!
>> >> > >
>> >> > > > > > That is why it is extremely important to have it clear,
>> >> > > > > > understandable, and even more important - easy to access and
>> edit
>> >> > > > > > if needed.
>> >> > >
>> >> > > That is a problem to which many solutions are available.
>> >> > >
>> >> > > > > >
>> >> > > > > > Having that in mind I want to raise a discussion here about
>> using
>> >> > > > > > a GRAV https://getgrav.org
>> >> > > > > > This is flat file CMS, with no backend database to support.
>> >> > >
>> >> > > Is that a matter of familiarity and/or legacy?
>> >> > > Are there existing docs managed by grav that want importing?
>> >> > >
>> >> > > Bear in mind that unless there's a pretty substantial legacy
>> >> > > to deal with, committers can be expected to come from a range
>> >> > > of different backgrounds and adapt to whatever tools are used
>> >> > > for a particular project.
>> >> > >
>> >> > > --
>> >> > > Nick Kew
>> >> > >
>> >> >
>> >>
>> >>
>> >>
>> >> --
>> >> Brian Spector
>> >> CEO
>> >> MIRACL
>> >>
>> >> T: +44 (0) 20 3389 8190
>> >> https://www.miracl.com
>> >> 81 Rivington Street
>> >> London UK, EC2A 3AY
>> >> Registered in England and Wales 7017635
>> >>
>>
>
>
>
> --
> Brian Spector
> CEO
> MIRACL
>
> T: +44 (0) 20 3389 8190
> https://www.miracl.com
> 81 Rivington Street
> London UK, EC2A 3AY
> Registered in England and Wales 7017635

Re: [DISCUSS] GRAV - flat file CMS

[Brian Spector <br...@miracl.com>]

Hi Anthony,

This whole discussion was actually about all of the project website,
including tech docs, on Grav for the reasons I outlined below.

As far as readthedocs goes, we like readthedocs.org and know of it.

However, it is turning into a commercial / paid for service.

See: https://docs.readthedocs.org/en/latest/business/index.html

We weren't really sure how the community would feel about the docs site
being hosted there?

As an aside, if no one minds readthedocs.org hosting the project's
documentation then certainly one of the main project contributors paying a
few bucks a month at Heroku or Dreamiest can't be all that controversial
either for at least the documentation and maybe demo side of things?

The other bit was that when we have run Sphinx and MKDocs in the past the
notation in Latex was really a bear to get to build out properly. Not sure
if that's changed but since we have a ton of math (being crypto) to
document, we have had good success with MathJax, and Grav has a plugin for
it:
https://github.com/sommerregen/grav-plugin-mathjax

Because Grav is just a flat file CMS you can get a deployment system going
using git hooks as well, with just a bit more work:
http://hibbittsdesign.org/blog/posts/2015-12-11-using-grav-with-github

Grav website content is written in Markdown. So that makes it easy to
modify, merge, write, etc and we can manage the content through version
control.

Are other projects using readthedocs?

We could just keep the main page a static file and link to docs and demos
from the main page?



On Wed, Apr 6, 2016 at 8:38 PM, anthony shaw <an...@gmail.com>
wrote:

> Hey,
>
> Why not just use https://readthedocs.org/
>
> Point it at the Git repo, it'll compile, construct, publish and host
> the documentation for you as well as build the docs automatically
> after every commit using git hooks. Supports Markdown and Restructured
> Text
>
> It's becoming the new standard in the Python world for doc hosting.
>
> Plus its free!
>
> On Thu, Apr 7, 2016 at 4:13 AM, Jamal Natour <ja...@miracl.com>
> wrote:
> > Okay that makes sense.
> >
> >
> > On Wed, Apr 6, 2016 at 6:46 PM, Brian Spector <br...@miracl.com>
> > wrote:
> >
> >> Grav was put forward by the MIRACL team because of several reasons.
> >>
> >> First, writing in JSON for any kind of technical documentation is not a
> low
> >> barrier to entry. Markdown is the proper way to do this to democratise
> the
> >> process. Actually Markdown and Latex, which is converted via MathJax dto
> >> nice cryptographic notation, which Grav supports. Keep in mind that a
> lot
> >> of the lower level docs and functionality needs to be written not by
> folks
> >> who understand JSON but are academic cryptographers who have already
> >> written their information in Latex. In our experience, doing this
> >> conversion via a static website generator such as Jekyll has produced
> >> spotty results.
> >>
> >> Second, again, Grav IS A FLAT REPO. It's flat file CMS. It's
> requirements
> >> are just a web server with PHP and two mod modules. You can see the
> >> requirements here: http://learn.getgrav.org/basics/requirements
> >> This isn't like we have asked to host Wordpress or some bloated
> monstrosity
> >> (sorry Wordpress lovers).
> >>
> >> Third, because it is flat we can do versioning control on the Markdown
> docs
> >> via Git or other version control system just as Jamal has suggested.
> That
> >> IS our intention. Whether that fits within the Apache Way or not, I'm
> not
> >> sure, but we want to make sure that the text information on the website
> can
> >> managed via a common developer utilised version control system, and Git
> >> would be our preference (actually GitHub). So clone the repo, make
> changes,
> >> make a pull request, etc. to merge your changes on the Markdown docs,
> which
> >> are the foundation of the website. So this ins't for just the technical
> >> docs, this is for the entire Milagro web site.
> >>
> >> Fourth, Grav has an extensive set of plugins and tooling that can
> enable a
> >> richer experience above and beyond just a flat file CMS site. Without
> going
> >> into laborious detail, we would like to have a discussion forum,
> automated
> >> form to auto-enrol folks into the Milagro Slack (our not having this has
> >> come up more than once already) and the ability to showcase some of the
> >> technologies that Milagro Project (incubating) has that are relevant to
> web
> >> apps and mobile authentication.
> >>
> >> Namely, these are Milagro MFA (multi-factor authentication) using the
> M-Pin
> >> Protocol. In short, we would like to be able to show this in the Milagro
> >> site. Here's the Pin Pad version, here is the headless version, etc.
> Makes
> >> sense, right?  While this certainly can be done in pure JavaScript, PHP
> is
> >> still the dominant language found on most production web sites, even
> today.
> >> Being able to inspect that code in the repo and have it demonstrable in
> the
> >> Milagro site itself makes the technology "real" in our view.
> >>
> >> @Nick Kew, hopefully this makes sense to you to carry the request to the
> >> infrastructure team? Not sure how we thought we were going to get their
> >> attention on the dev milagro list in the first place but smarter folks
> than
> >> me hopefully have worked this out.
> >>
> >> How do we get an answer from the infrastructure team on this?
> >>
> >> To reiterate, the question is:
> >>
> >> Will they host Grav, which is a flat file CMS, for the Milagro site? The
> >> requirements are listed here:
> >> http://learn.getgrav.org/basics/requirements
> >>
> >>
> >> On Wed, Apr 6, 2016 at 5:44 PM, Jamal Natour <ja...@miracl.com>
> >> wrote:
> >>
> >> >  > > Is that a matter of familiarity and/or legacy?
> >> > > > Are there existing docs managed by grav that want importing?
> >> > AFAIK there are no legacy requirements, and we want to be as open and
> >> > transparent a community as possible.
> >> > I'd really like this to be here is everything in a flat repo, so any
> >> > external contributors are as empowered to make changes as a Miracl
> staff
> >> > member.
> >> > We already do public development, with pull requests as our internal
> >> > workflow,  and I think that us publishing JSON for content and HTML
> for
> >> > layout from a public git repo is a fairly low bar to entry.
> >> >
> >> > I'm a little uncomfortable with us *needing* more than that for
> >> > documentation, as it suggest some business process is being delegated
> to
> >> > tooling.
> >> > If we have business needs to accommodate, we should split this off
> into a
> >> > possibly internal discussion on how *PE* and *DEVOPS* can best support
> >> > these needs.
> >> >
> >> > Otherwise, I'd prefer that docs are stored alongside code in git, and
> are
> >> > handled like code.
> >> > I'd would like to avoid any  "in-house only" magic to produce docs
> >> > especially where we must engage with people who cannot use such visual
> >> > tools due to visual impairment or other accessibility needs.
> >> >
> >> > Using a "Git first" workflow will allow us to support email, web,
> users
> >> of
> >> > assistive technologies, as well as a range of desktop and mobile
> clients.
> >> >
> >> >
> >> >
> >> >
> >> >
> >> >
> >> > On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <ni...@apache.org> wrote:
> >> >
> >> > > On Wed, 6 Apr 2016 14:36:49 +0300
> >> > > Vladislav Mitov <vl...@miracl.com> wrote:
> >> > >
> >> > > > I agree with Jamal. We can build it with some kind of static site
> >> > > > generator for convenience, but we don't need this thing on the
> server
> >> > > > for sure.
> >> > >
> >> > > Indeed.  Existing apache projects use a range of publishing
> >> > > models and templates.  We could certainly ping infra about
> >> > > using the Apache CMS if some folks would prefer, but I think
> >> > > they'd want a pretty compelling case to support a whole new
> >> > > system.
> >> > >
> >> > > The most likely trigger to adopt it would be demand coming
> >> > > from a range of projects.  As in, when git was introduced,
> >> > > or arguably even when svn replaced cvs!
> >> > >
> >> > > > > > That is why it is extremely important to have it clear,
> >> > > > > > understandable, and even more important - easy to access and
> edit
> >> > > > > > if needed.
> >> > >
> >> > > That is a problem to which many solutions are available.
> >> > >
> >> > > > > >
> >> > > > > > Having that in mind I want to raise a discussion here about
> using
> >> > > > > > a GRAV https://getgrav.org
> >> > > > > > This is flat file CMS, with no backend database to support.
> >> > >
> >> > > Is that a matter of familiarity and/or legacy?
> >> > > Are there existing docs managed by grav that want importing?
> >> > >
> >> > > Bear in mind that unless there's a pretty substantial legacy
> >> > > to deal with, committers can be expected to come from a range
> >> > > of different backgrounds and adapt to whatever tools are used
> >> > > for a particular project.
> >> > >
> >> > > --
> >> > > Nick Kew
> >> > >
> >> >
> >>
> >>
> >>
> >> --
> >> Brian Spector
> >> CEO
> >> MIRACL
> >>
> >> T: +44 (0) 20 3389 8190
> >> https://www.miracl.com
> >> 81 Rivington Street
> >> London UK, EC2A 3AY
> >> Registered in England and Wales 7017635
> >>
>



-- 
Brian Spector
CEO
MIRACL

T: +44 (0) 20 3389 8190
https://www.miracl.com
81 Rivington Street
London UK, EC2A 3AY
Registered in England and Wales 7017635

Re: [DISCUSS] GRAV - flat file CMS

[anthony shaw <an...@gmail.com>]

Hey,

Why not just use https://readthedocs.org/

Point it at the Git repo, it'll compile, construct, publish and host
the documentation for you as well as build the docs automatically
after every commit using git hooks. Supports Markdown and Restructured
Text

It's becoming the new standard in the Python world for doc hosting.

Plus its free!

On Thu, Apr 7, 2016 at 4:13 AM, Jamal Natour <ja...@miracl.com> wrote:
> Okay that makes sense.
>
>
> On Wed, Apr 6, 2016 at 6:46 PM, Brian Spector <br...@miracl.com>
> wrote:
>
>> Grav was put forward by the MIRACL team because of several reasons.
>>
>> First, writing in JSON for any kind of technical documentation is not a low
>> barrier to entry. Markdown is the proper way to do this to democratise the
>> process. Actually Markdown and Latex, which is converted via MathJax dto
>> nice cryptographic notation, which Grav supports. Keep in mind that a lot
>> of the lower level docs and functionality needs to be written not by folks
>> who understand JSON but are academic cryptographers who have already
>> written their information in Latex. In our experience, doing this
>> conversion via a static website generator such as Jekyll has produced
>> spotty results.
>>
>> Second, again, Grav IS A FLAT REPO. It's flat file CMS. It's requirements
>> are just a web server with PHP and two mod modules. You can see the
>> requirements here: http://learn.getgrav.org/basics/requirements
>> This isn't like we have asked to host Wordpress or some bloated monstrosity
>> (sorry Wordpress lovers).
>>
>> Third, because it is flat we can do versioning control on the Markdown docs
>> via Git or other version control system just as Jamal has suggested. That
>> IS our intention. Whether that fits within the Apache Way or not, I'm not
>> sure, but we want to make sure that the text information on the website can
>> managed via a common developer utilised version control system, and Git
>> would be our preference (actually GitHub). So clone the repo, make changes,
>> make a pull request, etc. to merge your changes on the Markdown docs, which
>> are the foundation of the website. So this ins't for just the technical
>> docs, this is for the entire Milagro web site.
>>
>> Fourth, Grav has an extensive set of plugins and tooling that can enable a
>> richer experience above and beyond just a flat file CMS site. Without going
>> into laborious detail, we would like to have a discussion forum, automated
>> form to auto-enrol folks into the Milagro Slack (our not having this has
>> come up more than once already) and the ability to showcase some of the
>> technologies that Milagro Project (incubating) has that are relevant to web
>> apps and mobile authentication.
>>
>> Namely, these are Milagro MFA (multi-factor authentication) using the M-Pin
>> Protocol. In short, we would like to be able to show this in the Milagro
>> site. Here's the Pin Pad version, here is the headless version, etc. Makes
>> sense, right?  While this certainly can be done in pure JavaScript, PHP is
>> still the dominant language found on most production web sites, even today.
>> Being able to inspect that code in the repo and have it demonstrable in the
>> Milagro site itself makes the technology "real" in our view.
>>
>> @Nick Kew, hopefully this makes sense to you to carry the request to the
>> infrastructure team? Not sure how we thought we were going to get their
>> attention on the dev milagro list in the first place but smarter folks than
>> me hopefully have worked this out.
>>
>> How do we get an answer from the infrastructure team on this?
>>
>> To reiterate, the question is:
>>
>> Will they host Grav, which is a flat file CMS, for the Milagro site? The
>> requirements are listed here:
>> http://learn.getgrav.org/basics/requirements
>>
>>
>> On Wed, Apr 6, 2016 at 5:44 PM, Jamal Natour <ja...@miracl.com>
>> wrote:
>>
>> >  > > Is that a matter of familiarity and/or legacy?
>> > > > Are there existing docs managed by grav that want importing?
>> > AFAIK there are no legacy requirements, and we want to be as open and
>> > transparent a community as possible.
>> > I'd really like this to be here is everything in a flat repo, so any
>> > external contributors are as empowered to make changes as a Miracl staff
>> > member.
>> > We already do public development, with pull requests as our internal
>> > workflow,  and I think that us publishing JSON for content and HTML for
>> > layout from a public git repo is a fairly low bar to entry.
>> >
>> > I'm a little uncomfortable with us *needing* more than that for
>> > documentation, as it suggest some business process is being delegated to
>> > tooling.
>> > If we have business needs to accommodate, we should split this off into a
>> > possibly internal discussion on how *PE* and *DEVOPS* can best support
>> > these needs.
>> >
>> > Otherwise, I'd prefer that docs are stored alongside code in git, and are
>> > handled like code.
>> > I'd would like to avoid any  "in-house only" magic to produce docs
>> > especially where we must engage with people who cannot use such visual
>> > tools due to visual impairment or other accessibility needs.
>> >
>> > Using a "Git first" workflow will allow us to support email, web, users
>> of
>> > assistive technologies, as well as a range of desktop and mobile clients.
>> >
>> >
>> >
>> >
>> >
>> >
>> > On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <ni...@apache.org> wrote:
>> >
>> > > On Wed, 6 Apr 2016 14:36:49 +0300
>> > > Vladislav Mitov <vl...@miracl.com> wrote:
>> > >
>> > > > I agree with Jamal. We can build it with some kind of static site
>> > > > generator for convenience, but we don't need this thing on the server
>> > > > for sure.
>> > >
>> > > Indeed.  Existing apache projects use a range of publishing
>> > > models and templates.  We could certainly ping infra about
>> > > using the Apache CMS if some folks would prefer, but I think
>> > > they'd want a pretty compelling case to support a whole new
>> > > system.
>> > >
>> > > The most likely trigger to adopt it would be demand coming
>> > > from a range of projects.  As in, when git was introduced,
>> > > or arguably even when svn replaced cvs!
>> > >
>> > > > > > That is why it is extremely important to have it clear,
>> > > > > > understandable, and even more important - easy to access and edit
>> > > > > > if needed.
>> > >
>> > > That is a problem to which many solutions are available.
>> > >
>> > > > > >
>> > > > > > Having that in mind I want to raise a discussion here about using
>> > > > > > a GRAV https://getgrav.org
>> > > > > > This is flat file CMS, with no backend database to support.
>> > >
>> > > Is that a matter of familiarity and/or legacy?
>> > > Are there existing docs managed by grav that want importing?
>> > >
>> > > Bear in mind that unless there's a pretty substantial legacy
>> > > to deal with, committers can be expected to come from a range
>> > > of different backgrounds and adapt to whatever tools are used
>> > > for a particular project.
>> > >
>> > > --
>> > > Nick Kew
>> > >
>> >
>>
>>
>>
>> --
>> Brian Spector
>> CEO
>> MIRACL
>>
>> T: +44 (0) 20 3389 8190
>> https://www.miracl.com
>> 81 Rivington Street
>> London UK, EC2A 3AY
>> Registered in England and Wales 7017635
>>

Re: [DISCUSS] GRAV - flat file CMS

[Jamal Natour <ja...@miracl.com>]

Okay that makes sense.


On Wed, Apr 6, 2016 at 6:46 PM, Brian Spector <br...@miracl.com>
wrote:

> Grav was put forward by the MIRACL team because of several reasons.
>
> First, writing in JSON for any kind of technical documentation is not a low
> barrier to entry. Markdown is the proper way to do this to democratise the
> process. Actually Markdown and Latex, which is converted via MathJax dto
> nice cryptographic notation, which Grav supports. Keep in mind that a lot
> of the lower level docs and functionality needs to be written not by folks
> who understand JSON but are academic cryptographers who have already
> written their information in Latex. In our experience, doing this
> conversion via a static website generator such as Jekyll has produced
> spotty results.
>
> Second, again, Grav IS A FLAT REPO. It's flat file CMS. It's requirements
> are just a web server with PHP and two mod modules. You can see the
> requirements here: http://learn.getgrav.org/basics/requirements
> This isn't like we have asked to host Wordpress or some bloated monstrosity
> (sorry Wordpress lovers).
>
> Third, because it is flat we can do versioning control on the Markdown docs
> via Git or other version control system just as Jamal has suggested. That
> IS our intention. Whether that fits within the Apache Way or not, I'm not
> sure, but we want to make sure that the text information on the website can
> managed via a common developer utilised version control system, and Git
> would be our preference (actually GitHub). So clone the repo, make changes,
> make a pull request, etc. to merge your changes on the Markdown docs, which
> are the foundation of the website. So this ins't for just the technical
> docs, this is for the entire Milagro web site.
>
> Fourth, Grav has an extensive set of plugins and tooling that can enable a
> richer experience above and beyond just a flat file CMS site. Without going
> into laborious detail, we would like to have a discussion forum, automated
> form to auto-enrol folks into the Milagro Slack (our not having this has
> come up more than once already) and the ability to showcase some of the
> technologies that Milagro Project (incubating) has that are relevant to web
> apps and mobile authentication.
>
> Namely, these are Milagro MFA (multi-factor authentication) using the M-Pin
> Protocol. In short, we would like to be able to show this in the Milagro
> site. Here's the Pin Pad version, here is the headless version, etc. Makes
> sense, right?  While this certainly can be done in pure JavaScript, PHP is
> still the dominant language found on most production web sites, even today.
> Being able to inspect that code in the repo and have it demonstrable in the
> Milagro site itself makes the technology "real" in our view.
>
> @Nick Kew, hopefully this makes sense to you to carry the request to the
> infrastructure team? Not sure how we thought we were going to get their
> attention on the dev milagro list in the first place but smarter folks than
> me hopefully have worked this out.
>
> How do we get an answer from the infrastructure team on this?
>
> To reiterate, the question is:
>
> Will they host Grav, which is a flat file CMS, for the Milagro site? The
> requirements are listed here:
> http://learn.getgrav.org/basics/requirements
>
>
> On Wed, Apr 6, 2016 at 5:44 PM, Jamal Natour <ja...@miracl.com>
> wrote:
>
> >  > > Is that a matter of familiarity and/or legacy?
> > > > Are there existing docs managed by grav that want importing?
> > AFAIK there are no legacy requirements, and we want to be as open and
> > transparent a community as possible.
> > I'd really like this to be here is everything in a flat repo, so any
> > external contributors are as empowered to make changes as a Miracl staff
> > member.
> > We already do public development, with pull requests as our internal
> > workflow,  and I think that us publishing JSON for content and HTML for
> > layout from a public git repo is a fairly low bar to entry.
> >
> > I'm a little uncomfortable with us *needing* more than that for
> > documentation, as it suggest some business process is being delegated to
> > tooling.
> > If we have business needs to accommodate, we should split this off into a
> > possibly internal discussion on how *PE* and *DEVOPS* can best support
> > these needs.
> >
> > Otherwise, I'd prefer that docs are stored alongside code in git, and are
> > handled like code.
> > I'd would like to avoid any  "in-house only" magic to produce docs
> > especially where we must engage with people who cannot use such visual
> > tools due to visual impairment or other accessibility needs.
> >
> > Using a "Git first" workflow will allow us to support email, web, users
> of
> > assistive technologies, as well as a range of desktop and mobile clients.
> >
> >
> >
> >
> >
> >
> > On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <ni...@apache.org> wrote:
> >
> > > On Wed, 6 Apr 2016 14:36:49 +0300
> > > Vladislav Mitov <vl...@miracl.com> wrote:
> > >
> > > > I agree with Jamal. We can build it with some kind of static site
> > > > generator for convenience, but we don't need this thing on the server
> > > > for sure.
> > >
> > > Indeed.  Existing apache projects use a range of publishing
> > > models and templates.  We could certainly ping infra about
> > > using the Apache CMS if some folks would prefer, but I think
> > > they'd want a pretty compelling case to support a whole new
> > > system.
> > >
> > > The most likely trigger to adopt it would be demand coming
> > > from a range of projects.  As in, when git was introduced,
> > > or arguably even when svn replaced cvs!
> > >
> > > > > > That is why it is extremely important to have it clear,
> > > > > > understandable, and even more important - easy to access and edit
> > > > > > if needed.
> > >
> > > That is a problem to which many solutions are available.
> > >
> > > > > >
> > > > > > Having that in mind I want to raise a discussion here about using
> > > > > > a GRAV https://getgrav.org
> > > > > > This is flat file CMS, with no backend database to support.
> > >
> > > Is that a matter of familiarity and/or legacy?
> > > Are there existing docs managed by grav that want importing?
> > >
> > > Bear in mind that unless there's a pretty substantial legacy
> > > to deal with, committers can be expected to come from a range
> > > of different backgrounds and adapt to whatever tools are used
> > > for a particular project.
> > >
> > > --
> > > Nick Kew
> > >
> >
>
>
>
> --
> Brian Spector
> CEO
> MIRACL
>
> T: +44 (0) 20 3389 8190
> https://www.miracl.com
> 81 Rivington Street
> London UK, EC2A 3AY
> Registered in England and Wales 7017635
>

Re: [DISCUSS] GRAV - flat file CMS

[Brian Spector <br...@miracl.com>]

Grav was put forward by the MIRACL team because of several reasons.

First, writing in JSON for any kind of technical documentation is not a low
barrier to entry. Markdown is the proper way to do this to democratise the
process. Actually Markdown and Latex, which is converted via MathJax dto
nice cryptographic notation, which Grav supports. Keep in mind that a lot
of the lower level docs and functionality needs to be written not by folks
who understand JSON but are academic cryptographers who have already
written their information in Latex. In our experience, doing this
conversion via a static website generator such as Jekyll has produced
spotty results.

Second, again, Grav IS A FLAT REPO. It's flat file CMS. It's requirements
are just a web server with PHP and two mod modules. You can see the
requirements here: http://learn.getgrav.org/basics/requirements
This isn't like we have asked to host Wordpress or some bloated monstrosity
(sorry Wordpress lovers).

Third, because it is flat we can do versioning control on the Markdown docs
via Git or other version control system just as Jamal has suggested. That
IS our intention. Whether that fits within the Apache Way or not, I'm not
sure, but we want to make sure that the text information on the website can
managed via a common developer utilised version control system, and Git
would be our preference (actually GitHub). So clone the repo, make changes,
make a pull request, etc. to merge your changes on the Markdown docs, which
are the foundation of the website. So this ins't for just the technical
docs, this is for the entire Milagro web site.

Fourth, Grav has an extensive set of plugins and tooling that can enable a
richer experience above and beyond just a flat file CMS site. Without going
into laborious detail, we would like to have a discussion forum, automated
form to auto-enrol folks into the Milagro Slack (our not having this has
come up more than once already) and the ability to showcase some of the
technologies that Milagro Project (incubating) has that are relevant to web
apps and mobile authentication.

Namely, these are Milagro MFA (multi-factor authentication) using the M-Pin
Protocol. In short, we would like to be able to show this in the Milagro
site. Here's the Pin Pad version, here is the headless version, etc. Makes
sense, right?  While this certainly can be done in pure JavaScript, PHP is
still the dominant language found on most production web sites, even today.
Being able to inspect that code in the repo and have it demonstrable in the
Milagro site itself makes the technology "real" in our view.

@Nick Kew, hopefully this makes sense to you to carry the request to the
infrastructure team? Not sure how we thought we were going to get their
attention on the dev milagro list in the first place but smarter folks than
me hopefully have worked this out.

How do we get an answer from the infrastructure team on this?

To reiterate, the question is:

Will they host Grav, which is a flat file CMS, for the Milagro site? The
requirements are listed here:
http://learn.getgrav.org/basics/requirements


On Wed, Apr 6, 2016 at 5:44 PM, Jamal Natour <ja...@miracl.com>
wrote:

>  > > Is that a matter of familiarity and/or legacy?
> > > Are there existing docs managed by grav that want importing?
> AFAIK there are no legacy requirements, and we want to be as open and
> transparent a community as possible.
> I'd really like this to be here is everything in a flat repo, so any
> external contributors are as empowered to make changes as a Miracl staff
> member.
> We already do public development, with pull requests as our internal
> workflow,  and I think that us publishing JSON for content and HTML for
> layout from a public git repo is a fairly low bar to entry.
>
> I'm a little uncomfortable with us *needing* more than that for
> documentation, as it suggest some business process is being delegated to
> tooling.
> If we have business needs to accommodate, we should split this off into a
> possibly internal discussion on how *PE* and *DEVOPS* can best support
> these needs.
>
> Otherwise, I'd prefer that docs are stored alongside code in git, and are
> handled like code.
> I'd would like to avoid any  "in-house only" magic to produce docs
> especially where we must engage with people who cannot use such visual
> tools due to visual impairment or other accessibility needs.
>
> Using a "Git first" workflow will allow us to support email, web, users of
> assistive technologies, as well as a range of desktop and mobile clients.
>
>
>
>
>
>
> On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <ni...@apache.org> wrote:
>
> > On Wed, 6 Apr 2016 14:36:49 +0300
> > Vladislav Mitov <vl...@miracl.com> wrote:
> >
> > > I agree with Jamal. We can build it with some kind of static site
> > > generator for convenience, but we don't need this thing on the server
> > > for sure.
> >
> > Indeed.  Existing apache projects use a range of publishing
> > models and templates.  We could certainly ping infra about
> > using the Apache CMS if some folks would prefer, but I think
> > they'd want a pretty compelling case to support a whole new
> > system.
> >
> > The most likely trigger to adopt it would be demand coming
> > from a range of projects.  As in, when git was introduced,
> > or arguably even when svn replaced cvs!
> >
> > > > > That is why it is extremely important to have it clear,
> > > > > understandable, and even more important - easy to access and edit
> > > > > if needed.
> >
> > That is a problem to which many solutions are available.
> >
> > > > >
> > > > > Having that in mind I want to raise a discussion here about using
> > > > > a GRAV https://getgrav.org
> > > > > This is flat file CMS, with no backend database to support.
> >
> > Is that a matter of familiarity and/or legacy?
> > Are there existing docs managed by grav that want importing?
> >
> > Bear in mind that unless there's a pretty substantial legacy
> > to deal with, committers can be expected to come from a range
> > of different backgrounds and adapt to whatever tools are used
> > for a particular project.
> >
> > --
> > Nick Kew
> >
>



-- 
Brian Spector
CEO
MIRACL

T: +44 (0) 20 3389 8190
https://www.miracl.com
81 Rivington Street
London UK, EC2A 3AY
Registered in England and Wales 7017635

Re: [DISCUSS] GRAV - flat file CMS

[Jamal Natour <ja...@miracl.com>]

 > > Is that a matter of familiarity and/or legacy?
> > Are there existing docs managed by grav that want importing?
AFAIK there are no legacy requirements, and we want to be as open and
transparent a community as possible.
I'd really like this to be here is everything in a flat repo, so any
external contributors are as empowered to make changes as a Miracl staff
member.
We already do public development, with pull requests as our internal
workflow,  and I think that us publishing JSON for content and HTML for
layout from a public git repo is a fairly low bar to entry.

I'm a little uncomfortable with us *needing* more than that for
documentation, as it suggest some business process is being delegated to
tooling.
If we have business needs to accommodate, we should split this off into a
possibly internal discussion on how *PE* and *DEVOPS* can best support
these needs.

Otherwise, I'd prefer that docs are stored alongside code in git, and are
handled like code.
I'd would like to avoid any  "in-house only" magic to produce docs
especially where we must engage with people who cannot use such visual
tools due to visual impairment or other accessibility needs.

Using a "Git first" workflow will allow us to support email, web, users of
assistive technologies, as well as a range of desktop and mobile clients.






On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <ni...@apache.org> wrote:

> On Wed, 6 Apr 2016 14:36:49 +0300
> Vladislav Mitov <vl...@miracl.com> wrote:
>
> > I agree with Jamal. We can build it with some kind of static site
> > generator for convenience, but we don't need this thing on the server
> > for sure.
>
> Indeed.  Existing apache projects use a range of publishing
> models and templates.  We could certainly ping infra about
> using the Apache CMS if some folks would prefer, but I think
> they'd want a pretty compelling case to support a whole new
> system.
>
> The most likely trigger to adopt it would be demand coming
> from a range of projects.  As in, when git was introduced,
> or arguably even when svn replaced cvs!
>
> > > > That is why it is extremely important to have it clear,
> > > > understandable, and even more important - easy to access and edit
> > > > if needed.
>
> That is a problem to which many solutions are available.
>
> > > >
> > > > Having that in mind I want to raise a discussion here about using
> > > > a GRAV https://getgrav.org
> > > > This is flat file CMS, with no backend database to support.
>
> Is that a matter of familiarity and/or legacy?
> Are there existing docs managed by grav that want importing?
>
> Bear in mind that unless there's a pretty substantial legacy
> to deal with, committers can be expected to come from a range
> of different backgrounds and adapt to whatever tools are used
> for a particular project.
>
> --
> Nick Kew
>

Re: [DISCUSS] GRAV - flat file CMS

[Nick Kew <ni...@apache.org>]

On Wed, 6 Apr 2016 14:36:49 +0300
Vladislav Mitov <vl...@miracl.com> wrote:

> I agree with Jamal. We can build it with some kind of static site
> generator for convenience, but we don't need this thing on the server
> for sure.

Indeed.  Existing apache projects use a range of publishing
models and templates.  We could certainly ping infra about
using the Apache CMS if some folks would prefer, but I think
they'd want a pretty compelling case to support a whole new
system.

The most likely trigger to adopt it would be demand coming
from a range of projects.  As in, when git was introduced,
or arguably even when svn replaced cvs!

> > > That is why it is extremely important to have it clear,
> > > understandable, and even more important - easy to access and edit
> > > if needed.

That is a problem to which many solutions are available.

> > >
> > > Having that in mind I want to raise a discussion here about using
> > > a GRAV https://getgrav.org
> > > This is flat file CMS, with no backend database to support.

Is that a matter of familiarity and/or legacy?
Are there existing docs managed by grav that want importing?

Bear in mind that unless there's a pretty substantial legacy
to deal with, committers can be expected to come from a range
of different backgrounds and adapt to whatever tools are used
for a particular project.

-- 
Nick Kew

Re: [DISCUSS] GRAV - flat file CMS

[Vladislav Mitov <vl...@miracl.com>]

I agree with Jamal. We can build it with some kind of static site generator
for convenience, but we don't need this thing on the server for sure.

Cheers,
Vladi

On Wed, Apr 6, 2016 at 2:32 PM, Jamal Natour <ja...@miracl.com>
wrote:

> Please, please - plain html5/css and jquery.
>
> It's just a doc website, and we really should not overcomplicate matters.
>
> If we need specific functionalitity, we should have a business case for it,
> otherwise YAGNI.
>
> my 2p
> jamal
>
>
>
> On Wed, Apr 6, 2016 at 11:34 AM, Tomasz Matecki <tomasz.matecki@miracl.com
> >
> wrote:
>
> > Welcome all,
> >
> > While the project Milagro Apache (incubating) is going to be announced
> and
> > introduce to Apache community in beginning of May we are about to create
> > new website - the place for all our community activities and main POC
> with
> > our prospect users.
> > That is why it is extremely important to have it clear, understandable,
> > and even more important - easy to access and edit if needed.
> >
> > Having that in mind I want to raise a discussion here about using a GRAV
> > https://getgrav.org
> > This is flat file CMS, with no backend database to support.
> >
> > We are thinking of using GRAV in terms of both - website itself and
> > documentation pages.
> >
> > While it is not a standard for for incubator project and not even for
> > graduated Apache projects - if we want to use it we need to ask the
> > infrastructure team to support the Milagro website being hosted on an
> > Apache Web Server using an open source flat file CMS - GRAV.
> >
> > Please can you place your comments or thoughts here.
> > I want to encourage everyone on this list to use this form of
> > communication and discussion more often and more actively - as this is a
> > best practice and standard tool for projects under ASF
> >
> > I know that for most of us it is first project under Apache - so let’s
> try
> > to work in Apache way
> >
> > *And finally I’d like to remind the MILAGRO is currently in INCUBATION
> > stage -  so that mean we CAN NOT use “Apache Milagro” statement in any
> > communication, so please have this in mind.*
> > *Variants like "Apache Milagro (incubating)", or "The Milagro project,
> > currently in incubation at Apache” are fine - so please use those
> instead. *
> >
> > Regards
> > Tomasz Matecki
> >
> >
> >
> >
>

Re: [DISCUSS] GRAV - flat file CMS

[Brian Spector <br...@miracl.com>]

Yes, there is a good reason to do this. Otherwise, we would not have asked.

Brian

On Wed, Apr 6, 2016 at 12:32 PM, Jamal Natour <ja...@miracl.com>
wrote:

> Please, please - plain html5/css and jquery.
>
> It's just a doc website, and we really should not overcomplicate matters.
>
> If we need specific functionalitity, we should have a business case for it,
> otherwise YAGNI.
>
> my 2p
> jamal
>
>
>
> On Wed, Apr 6, 2016 at 11:34 AM, Tomasz Matecki <tomasz.matecki@miracl.com
> >
> wrote:
>
> > Welcome all,
> >
> > While the project Milagro Apache (incubating) is going to be announced
> and
> > introduce to Apache community in beginning of May we are about to create
> > new website - the place for all our community activities and main POC
> with
> > our prospect users.
> > That is why it is extremely important to have it clear, understandable,
> > and even more important - easy to access and edit if needed.
> >
> > Having that in mind I want to raise a discussion here about using a GRAV
> > https://getgrav.org
> > This is flat file CMS, with no backend database to support.
> >
> > We are thinking of using GRAV in terms of both - website itself and
> > documentation pages.
> >
> > While it is not a standard for for incubator project and not even for
> > graduated Apache projects - if we want to use it we need to ask the
> > infrastructure team to support the Milagro website being hosted on an
> > Apache Web Server using an open source flat file CMS - GRAV.
> >
> > Please can you place your comments or thoughts here.
> > I want to encourage everyone on this list to use this form of
> > communication and discussion more often and more actively - as this is a
> > best practice and standard tool for projects under ASF
> >
> > I know that for most of us it is first project under Apache - so let’s
> try
> > to work in Apache way
> >
> > *And finally I’d like to remind the MILAGRO is currently in INCUBATION
> > stage -  so that mean we CAN NOT use “Apache Milagro” statement in any
> > communication, so please have this in mind.*
> > *Variants like "Apache Milagro (incubating)", or "The Milagro project,
> > currently in incubation at Apache” are fine - so please use those
> instead. *
> >
> > Regards
> > Tomasz Matecki
> >
> >
> >
> >
>



-- 
Brian Spector
CEO
MIRACL

T: +44 (0) 20 3389 8190
https://www.miracl.com
81 Rivington Street
London UK, EC2A 3AY
Registered in England and Wales 7017635