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.
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.
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…
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.