RFC: Move to using an external documentation builder like readthedocs.org

[robbieaverill]

This is a placeholder for discussion around moving the SilverStripe documentation to something like readthedocs.org.

---

I've had a bit of a play with RTFD (readthedocs.org) and can say that it's easy enough to spin up a comparable documentation site to our current implementation (docs.silverstripe.org) with minimal configuration.

Some of the benefits:

• "Follow the trend"
• GitHub hook integrations, updates on merge - changes are automatically recompiled and displayed on the docs site
• PDF/EPUB export of each build

Current blockers:

• Our documentation is all in markdown. While RTFD supports mkdocs and can build our current documentation, it doesn't support custom themes unless we were to convert to using Sphinx (python based). Reference: MkDocs builds: allow to use MkDocs own themes readthedocs/readthedocs.org#978

Options

• Wait for RTFD to support mkdocs themes
• Take mkdocs + the base RTFD theme as a starting point and create our own
• Contribute to RTFD to help with supporting mkdocs themes (may or may not be feasible)
• Convert to using Sphinx for documentation (not ideal)

Other considerations

• Various redirects would need to be set up in RTFD to support changes in file structure between versions (OOB functionality in the UI)
• Docs would need to be restructured a little bit to fit the RTFD format - this wouldn't be too drastic at a first glance
• Remove legacy :::php style code formatting in favour of triple backticks (GFM)

---

Some general comments:

• It takes RTFD about 90 seconds to build a branch of our framework's documentation from scratch
• CMS and other modules can be included in the framework docs as "submodules" which "live within the same namespace/CNAME".
• OOB branch displaying is "latest" and "stable". These can both be disabled, and "stable" can be configured to point to another version. "latest" can be pointed at a certain branch but defaults to the default for the VCS you use, i.e. "master"

[madmatt]

If we're considering switching to rST, this article might be useful (though no doubt biased): http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

[robbieaverill]

Reasonable points. I appreciate the notes on not being extensible (which is relevant for SS syntax highlighting) or providing contexts like warnings, which are relevant for technical docs.

[dhensby]

What's the effort involved in moving to Sphinx for docs? At the moment our docs have some hacks to get custom titles and so on, maybe a proper standard would be better for us?

I like the idea of moving to RTD - how much will we need to re-organise the existing docs?

[robbieaverill]

@dhensby RTD picks up and generates a pretty reasonable set of our docs with no changes. We'd need to restructure it a little bit, but nothing major. Here's the example.

[SpiritLevel]

Howdy! This RFC seems related to docsviewer. Some questions/comments come to mind:

(1) is docsviewer going to be updated to SS4 ? I find docsviewer useful for providing within-site-docs for site admin people.
(2) if docsviewer is going to be updated and actively maintained, it seems to me that having the SS docs using docsviewer is a good way to 'dogfood' it: having to keep SS docs looking good provides the impetus to maintain the docsviewer module. Also, using docsviewer allows for greater customisation. If customisation is not needed/desired, the custom hacks that Dan mentions are easily removed to make docsviewer only render pure markdown.

:)

Edit: In academia, the standard for writing technical documents (articles,theses,books,...) is LaTeX. There seem to be methods for rendering LaTeX in browsers. Writing in LaTeX is a bit more work than writing in markdown but it is very html-like and so is nice and semantic. LaTeX produces beautiful typography, has great features for tables of contents, lists of figures, glossaries, indexes, handling images, citations, cross-referencing...LaTeX is capable of handling the most complex of documents.

Second Edit: no problem with getting LaTeX syntax highlighting in all major editors. Also, PHPStorm has a plugin for LaTeX.

[robbieaverill]

(1) is docsviewer going to be updated to SS4 ? I find docsviewer useful for providing within-site-docs for site admin people.

I imagine it will be upgraded, yeah.

[dhensby]

Whilst LaTeX is very powerful and useful for writing scientific documentation, we need to be careful not to fall into NIH syndrome.

Using something like RTD will save us a lot of internal hassle around maintaining the docs site and can streamline our docs flow a bit more. To dismiss it and had roll LaTeX markup and hosting would be to focus on the wrong thing right now.

[madmatt]

Is it worth it to move to rST though? I doubt if we can use the 'default theme' you get with RTD, it's a bit bland (and doesn't support useful things like "show children pages of this page as a TOC list" as far as I can tell (though I've not looked into it too far).

[SpiritLevel]

@dhensby When you say "internal hassle", what exactly are you referring to ? The process of building the docs after the content has been updated ? Or are there other internal hassles ?

[dhensby]

Other internal hassles that come with hosting a docs site, maintaining a front end and so on

[SpiritLevel]

Just playing devil's advocate here: it seems that the net gains by moving to RTD are really, really small, if there are any at all.

The hosting ought to be easy with SS Platform (providing an additional opportunity for SS Platform dogfooding) and the amount of front-end work to keep docs.ss.org looking ok is minimal since it involves only minor tweaks of docsviewer, which, along with ss.org, is being maintained anyway. The daily docs build might be a bit of work but ultimately that is automated.

And moving to RTD would eliminate SS's ability to offer a customised and distinct experience, including useful features like easy linking to api.ss.org, while RTD only offers a "bland theme" with somewhat awkward menu navigation.

I suppose I just don't see much rationale for a move, especially since all of these content delivery issues pale enormously in comparison to the need to improve the actual organisation and content of all the documentation, not just developer docs. It is almost as if these delivery issues constitute a "focus on the wrong thing right now" (sorry, Dan, couldn't resist ;P ) Anyhow, enough said: just my two cents worth! :)

[robbieaverill]

One of the most important benefits for moving (for me) is that you get an OOB GitHub integration for re-building the docs whenever a PR is merged, new release tagged, etc. We could build one of these ourselves too of course.

[dhensby]

I agree that the docs would benefit from a restructuring and better organisation, I actually think RTDs basic nav will help us focus on that as we begin to realise that our deeply nested docs arent particularly condusive to helping people learn SS. There's currently a lot more emphasis on knowing what you need to look for over being able to find things easily

[robbieaverill]

Yes, I found more out about the overall structure from looking at the RTD example for a couple of minutes than having used the docs for some time.

[SpiritLevel]

Actually, the docs don't seem too deeply nested and the structure is not too complicated:

https://github.com/silverstripe/silverstripe-framework/tree/master/docs/en

It would be easy enough to reorganise the file hierarchy, whichever way the docs are viewed. No, the hard part is writing and editing the content, which will require effort, whichever way the docs are viewed.

IMHO, the docs are much more visually pleasing to read in docsviewer than RTD. With some minor tidying up of docsviewer when it is upgraded to SS4, the quality of presentation and the availability of custom features (index generation, api and other specialised tags) will exceed what you can get with RTD. If docsviewer were not going to be upgraded to SS4 then my argument is moot and RTD is an obvious solution :) But, since docsviewer is being maintained anyways...

[chillu]

Haven't really caught up with the nuances of this discussion, but I'll just point out that you can script a conversion from Markdown to reStructuredText. If I could go back to when I made the decision to convert the Dokuwiki markup to Markdown for our original documentation, I would've used reStructuredText.

[chillu]

Notes on RST:

• Looking at the differences between Markdown and RST, I don't think it'll be too hard for docs contributors to learn the new syntax. The main difference for the small subset of markup we're using is probably the link format (see syntax guide)

Notes on RTD:

• RTD is only going to save us work if we stay close to the default theme (with a SilverStripe logo, link colours, and a custom top menu). If we try to make it look like the current docs site, it's quite likely less work to just suck it up and keep patching around docsviewer.
• RTD has user-defined redirects, which should smooth the migration path
• RTD runs ethical ads, but you can opt out through a donation-based Gold membership for at least 20USD/month
• No guarantees with the free RTD. They're serving 70k projects and 20m page views per month, incl. high profile projects like Doctrine
• RTD is based on Sphinx, a python-based docs generator. If we outgrow their capabilities, we could generate the docs ourselves (e.g. via AWS Lambda), and host them from AWS S3. In that case, we could use a free Algolia to search the latest version of the content (5k docs limit), but would need to push content via their API (crawler costs extra)
• There's a huge number of projects using Sphinx. Big names are the CodeIgniter User Guide, Varnish, Graylog, phpMyAdmin, Typo3, Wagtail, CakePHP, Chef, Guzzle, Selenium.
• Free RTD provides custom domains and fulltext search (see features)
• We can run our own Google Analytics
• I'm not 100% clear if we can replicate our custom [api] markup. There's Sphinx docs for extensions, but it looks like a few hours of work. Maybe we should just admit defeat and use a standard URL for this: e.g. [DataObject](http://api.silverstripe.org/?q=DataObject)
• We get search out of the box

[clarkepaul]

I think the docs site should be more theme-able than just a SilverStripe logo so unless we have quite some control over the presentation of the docs I'm not that keen (also that default theme is not visually accessible). It seems it would be fairly easy to create paths between docs and ss.org which needs consideration for new comers if we move it.

If we navigate away from DocsViewer we are likely to neglect User Help unless it makes the move as well. I feel there is even more reason for User Help to be SS themed or built into the CMS so that it can be personally customised.

[robbieaverill]

Another idea to throw into this, maybe we could move all of our documentation into a separate repository. This could potentially also include userhelp documentation, or do the same for userhelp documentation in a separate repo.

[chillu]

Facebook has built an open source docs generator (through Markdown, built with React): https://docusaurus.io/

[robbieaverill]

I've just spent a bit of time investigating Docusaurus and how it might work for us. Here are some notes:

General notes (v1)

• It's designed to build a website for your project, where documentation is the primary component of it. This means that out of the box it gives you a lightweight page building system, router, etc, and one of the links in the header is "Docs" which is where the actual markdown files are served from. We could ignore part of that and go straight to docs.
• Docusaurus is employed as an npm module, rather than part of the project code. This means that customising it would be difficult. If we needed to change anything, we would need to fork it or contribute changes back to the origin repo.
• I was able to generate the framework index documentation file easily with a symlink to another path where the code is stored, which means that the documentation source files don't have to be part of the Docusaurus website/project repository.
• It doesn't support multi-repo splits for documentation yet. See Versioning with Multirepo and Monorepo facebook/docusaurus#852. This would be a blocker for sites like userhelp, unless we decided to combine all our documentation into a single repository.
• It looks like it's designed for small projects with a limited amount of documentation. We have quite a lot of documentation, and a nested folder structure for it, which may not work particularly well (see below).
• The left hand sidebar navigation is hard coded via configuration. Ours is currently dynamic based on the documentation folder structure.

v2 specific notes

Note that v2 is in alpha at the moment.

• Docusaurus v2 removes its responsibility for managing the layout, and introduces support for themes.
• D2 supports plugins, which would be essential for us to support things like our API site syntax integration (without changing our source docs to use full URLs).
• RFC for supporting plugins, themes, and presents: [RFC] Plugins/Themes/Presets API facebook/docusaurus#1438

There's a great comparison list of D1 problems here: facebook/docusaurus#789

TL;DR

I don't think Docusaurus will work for us at least until v2 is stable.

[robbieaverill]

So a couple of years in, we've investigated a couple of different options for how we generate our documentation and haven't found anything as suitable as what we've already got. The hope was that we could achieve more of a pre-built static site, which can integrate easily with GitHub events, and one which ideally involves less maintenance for the SilverStripe Ltd team.

Neither RTD nor Docusaurus seem like good candidates in the end, so perhaps the best solution is for us to upgrade our docsviewer module for SilverStripe 4 and potentially even rebuild the architecture so it's more capable of achieving the things we'd hoped to achieve by moving away from it - for example, we could add a webhook into TravisCI so that docs.silverstripe.org could be rebuilt whenever a build runs on specific branches, and remove the nightly cron which does that instead.

The docs.silverstripe.org site is probably the easiest example of how we use this module, since all of the content comes from silverstripe/framework.

The userhelp.silverstripe.org website however pulls content from 10-20 different modules - this is a definite maintenance pain point for us, in that it currently relies on branches such as 3.5 existing for a given module. Standard practice for us as module maintainers is to delete branches for versions that are no longer supported, however this breaks the userhelp website which is still referencing them. There was talk about building documentation from Git tags rather than branches, but we usually exclude our docs from tags. We could stop doing that, but it would be slightly detrimental for developers, since the distributable packages would then be slightly larger in size (particularly in framework, where most of our docs are) (this example is docs.silverstripe.org specific).

[chillu]

unless we decided to combine all our documentation into a single repository.

Couldn't this just be a pre-build step where it pulls in all content into a temporary markdown folder?

[robbieaverill]

Yeah, true. It wouldn't be a blocker at all, but would add a bit of extra time to write the script to stitch it all together.

[unclecheese]

As a way to learn Gatsby, I converted the docs site to use Gatsby.It works really well. Every time you push a commit to framework, it rebuilds the site statically. Deploys to netlify for free. Uses algolia's free docs search offering. Will have to reimplement some of the DocsParser methods for the api: magic. But those all translate really well to JS (just regex)

I haven't read through the whole thread, but I think documentation is a really key conversion point for our developer audience, and it's something we need to get right. Having control over it is really important, IMO. As long as the tooling mitigates our maintenance costs, I don't see a problem with it.

[unclecheese]

POC for Gatsby docs is here: https://ss-docs-gatsby.netlify.com

Source code https://github.com/unclecheese/silverstripe-framework/tree/pulls/4/gatsby-docs/docs/docs.silverstripe.org (adds a subdirectory of framework/docs)

Search doesn't work yet. Algolia are dragging their feet on getting me a key, because they don't like the content.

[robbieaverill]

Looks great @unclecheese! I'm keen to see how it'll end up working with versioning

[unclecheese]

New site is live. Closing.

[robbieaverill]

Speedy turnaround, nice work @unclecheese =D