Document modules using mkdocs

Have you looked at mkdocs? http://www.mkdocs.org/

Is generates a static website that is very fast. I’ve been using it for the
VTKExamples: https://lorensen.github.io/VTKExamples/site/

It does have hooks for a google custom search engine, google analytics.
Also several look feel’s. I chose the material look
http://squidfunk.github.io/mkdocs-material/ . It is built using
Google’s Material
Design https://material.io/guidelines/material-design/ guidelines.

I use github pages to host the source repository and the static site. I
admit I had special requirements since the bulk of the VTKExamples site is
source code.

I did not look at readthedocs.

Bill

Here’s a talk I gave at Kitware recently…

https://github.com/lorensen/VTKExamples/blob/master/src/Artifacts/VTKExamplesStatus2017.pdf

Using MkDocs for Slicer core documentation:
My understanding is that MkDocs uses Markdown as input format. We’ve been considering Markdown for Slicer core documentation but it seemed that “standard” Markdown was too limited and we did not want to choose a certain flavor, that is only understood by a single software. RestructedText with Sphinx generator seemed a more powerful and standardized option. We’ve created a couple of pages (see for example here: http://slicer.readthedocs.io/en/latest/user_guide/module_segmenteditor.html) and it works OK, but we’ll see how it holds up when we add more content.

Using MkDocs for extension documentation:
Historically (when there were no easily available free hosting available) extensions were documented on the slicer wiki, but this does not make much sense anymore. Typically, when we receive request to add a new extension, it comes without any documentation. As a minimum, we ask people to write a short description and tutorial in the readme.md file in their github repository - which is probably the simplest possible thing to do. There is no need to set up any extra generator for documentation, as github’s basic rendering is acceptable.

@Lorensen How do you think mkdocs could fit into the picture? How it could be used for improving what we have now?

rst is certainly more powerful (and complicated) than markdown. rst is more suited to “technical writers” than markdown which is quite simple, yet limited. For the main Slicer documentation I can see how rst is the right choice. The Slicer core team is sophisticated and can do a great job with rst/Sphinx. In my case, for VTKExamples, markdown is a better fit since 90% of the site is generated automatically from source code and simple markdown.

Another platform that uses Markdown is GitBook, we use it to document some of our extensions, eg https://qiicr.gitbooks.io/dcmqi-guide/content/

The added benefit of GitBook is that it provides a rich text editor in-browser, and supports collaborative development via change requests and questions, which means non-technical users can contribute changes to the content, or ask questions about the content, without ever having to learn what git is. For the full disclosure - we have not reached a point when we get content from arbitrary users, but it is possible…

Here is a comparison of MediaWiki, and GitHub+GitBook
See https://www.slicer.org/wiki/Documentation/Labs/DocumentationImprovments#New_Platform:_Comparison

GitBook … reached a point when we get content from arbitrary users

I was able to contact GitBook team but they didn’t follow up when I asked about getting free access for Slicer users.

A nice feature of mkdocs, since it generates a static site, a user can
preview the entire website before committing changes with a browser
using

python -m SimpleHTTPServer

For example, you can work disconnected from the internet (on a plane,
in New Hampshire, on the Mass Pike, etc.)

Being able to generate the extension locally is important, both sphinx and mkdocs support this.

With sphinx, you can simply open the generated index.html

I retract my suggestion for considering GitBook at all. In the recent upgrade of the system, GitBook made (in my view) an unfortunate decision to move to a proprietary format for content markup, without providing any documentation or any way to edit the content directly as text. The only way to edit content is via their own web-based editor. This works quite well as long as you use the features that work, but it is easy to get stuck once one deviates from that, or encounters a bug (of which there are many). After all the hopes I had for GitBook, I have to say it did not live to (my) expectations. ReadTheDocs is a better choice.