# Document modules using mkdocs

**URL:** <https://discourse.slicer.org/t/document-modules-using-mkdocs/1205>\
**Category:** Development\
**Created:** [October 10, 2017, 11:25pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205 "2017-10-10T23:25:18Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![Lorensen](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lorensen/32/31_2.png) [@Lorensen](https://discourse.slicer.org/u/Lorensen)\
**Post date:** [October 10, 2017, 11:25pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/1 "2017-10-10T23:25:18Z")

</div>

Have you looked at mkdocs? [http://www.mkdocs.org/](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/](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/](http://squidfunk.github.io/mkdocs-material/) . It is built using  
Google’s Material  
Design [https://material.io/guidelines/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

---

<div class="post-metadata">

**Author:** ![Lorensen](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lorensen/32/31_2.png) [@Lorensen](https://discourse.slicer.org/u/Lorensen)\
**Post date:** [October 10, 2017, 11:29pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/2 "2017-10-10T23:29:16Z")

</div>

Here’s a talk I gave at Kitware recently…

[https://github.com/lorensen/VTKExamples/blob/master/src/Artifacts/VTKExamplesStatus2017.pdf](https://github.com/lorensen/VTKExamples/blob/master/src/Artifacts/VTKExamplesStatus2017.pdf)

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [October 12, 2017, 3:28pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/3 "2017-10-12T15:28:30Z")

</div>

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](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](http://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?

---

<div class="post-metadata">

**Author:** ![Lorensen](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lorensen/32/31_2.png) [@Lorensen](https://discourse.slicer.org/u/Lorensen)\
**Post date:** [October 12, 2017, 4:02pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/4 "2017-10-12T16:02:37Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![fedorov](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/fedorov/32/14_2.png) [@fedorov](https://discourse.slicer.org/u/fedorov)\
**Post date:** [October 12, 2017, 8:21pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/5 "2017-10-12T20:21:58Z")

</div>

Another platform that uses Markdown is GitBook, we use it to document some of our extensions, eg [https://qiicr.gitbooks.io/dcmqi-guide/content/](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…

---

<div class="post-metadata">

**Author:** ![jcfr](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jcfr/32/17825_2.png) [@jcfr](https://discourse.slicer.org/u/jcfr)\
**Post date:** [October 12, 2017, 8:35pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/6 "2017-10-12T20:35:58Z")

</div>

Here is a comparison of MediaWiki, and GitHub+GitBook  
See [Documentation/Labs/DocumentationImprovments - Slicer Wiki](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.

---

<div class="post-metadata">

**Author:** ![Lorensen](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lorensen/32/31_2.png) [@Lorensen](https://discourse.slicer.org/u/Lorensen)\
**Post date:** [October 12, 2017, 11:19pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/7 "2017-10-12T23:19:01Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![jcfr](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jcfr/32/17825_2.png) [@jcfr](https://discourse.slicer.org/u/jcfr)\
**Post date:** [October 13, 2017, 7:42pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/8 "2017-10-13T19:42:47Z")

</div>

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`

---

<div class="post-metadata">

**Author:** ![fedorov](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/fedorov/32/14_2.png) [@fedorov](https://discourse.slicer.org/u/fedorov)\
**Post date:** [October 29, 2018, 8:30pm UTC](https://discourse.slicer.org/t/document-modules-using-mkdocs/1205/9 "2018-10-29T20:30:01Z")

</div>

> [@fedorov](#):
>
> Another platform that uses Markdown is GitBook, we use it to document some of our extensions, eg [https://qiicr.gitbooks.io/dcmqi-guide/content/](https://qiicr.gitbooks.io/dcmqi-guide/content/)

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.