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 <[email protected]> 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 <[email protected]> > 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 <[email protected]> > > 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 <[email protected]> > >> wrote: > >> > Okay that makes sense. > >> > > >> > > >> > On Wed, Apr 6, 2016 at 6:46 PM, Brian Spector < > [email protected]> > >> > 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 < > [email protected]> > >> >> 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 <[email protected]> wrote: > >> >> > > >> >> > > On Wed, 6 Apr 2016 14:36:49 +0300 > >> >> > > Vladislav Mitov <[email protected]> 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
