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
