# Document modules on readthedocs

**URL:** <https://discourse.slicer.org/t/document-modules-on-readthedocs/330>\
**Category:** Development\
**Created:** [May 16, 2017, 7:46pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330 "2017-05-16T19:46:17Z")\
**Posts on this page:** 20\
**Page:** 1

<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:** [May 16, 2017, 7:46pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/1 "2017-05-16T19:46:17Z")

</div>

I quite like the [Slicer documentation on readthedocs](http://slicer.readthedocs.io/en/latest/index.html). I would like to try to write documentation for the Segment editor module there.

@jcfr How can I contribute? Should I push changes into the [rst-user-and-dev-guide branch on GitHub](https://github.com/Slicer/Slicer/tree/rst-user-and-dev-guide/Docs)? Or should I wait for getting this branch merged to master?

---

<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:** [May 16, 2017, 8:21pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/2 "2017-05-16T20:21:35Z")

</div>

Great. Thanks for the feedback

For now, since readthedocs is configured to build the associated documentation, I suggest you push to this branch.

Note that I just rebased it on top of master. And since only both of us are working on this branch … do not hesitate to rebase it at your convenience.

---

<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:** [May 16, 2017, 8:43pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/3 "2017-05-16T20:43:57Z")

</div>

Looks nice. But how does this differ from using github pages?

I’m experimenting with it here:  
[https://lorensen.github.io/VTKExamples](https://lorensen.github.io/VTKExamples)

---

<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:** [May 16, 2017, 8:52pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/4 "2017-05-16T20:52:08Z")

</div>

> [@Lorensen](#):
>
> Looks nice. But how does this differ from using github pages?

Few advantages, in addition of providing free hosting, Readthedocs provides:

- a free worker node that will rebuild the documentation each time it is needed

- management of documentation version

- support for downloading pdf and/or ebook

- central location … looking on the readthedocs for documentation become the norm (at least for project adopting sphinx and/or python based)

Using Github is totally possible but you would have explicitly setup yet an other machine to rebuild and push documentation every night or continuously

---

<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:** [May 16, 2017, 8:52pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/5 "2017-05-16T20:52:40Z")

</div>

> [@Lorensen](#):
>
> I’m experimenting with it here:  
> [https://lorensen.github.io/VTKExamples](https://lorensen.github.io/VTKExamples)

Well done. These look quite nice 👍

---

<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:** [May 16, 2017, 9:04pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/6 "2017-05-16T21:04:08Z")

</div>

On github, the pages are automatically updated when changes are pushed.

---

<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:** [May 16, 2017, 9:05pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/7 "2017-05-16T21:05:36Z")

</div>

I still have some minor issues but it looks a lot better than the gitlab  
wiki.

---

<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:** [May 16, 2017, 9:10pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/8 "2017-05-16T21:10:11Z")

</div>

> [@Lorensen](#):
>
> On github, the pages are automatically updated when changes are pushed

Exactly, and that is great. That said, this happens in two cases:

- regular HTML is published
- [jekyll](https://jekyllrb.com/) based templates are used

In our case, documentation is written using RestructedText (with some markdown) and it first needs to be processed by [sphinx](http://www.sphinx-doc.org) toolchain before we obtain HTML. And it turns our ReadTheDocs will take care of running the sphinx toolchain for us.

> [@Lorensen](#):
>
> I still have some minor issues but it looks a lot better than the gitlab  
> wiki.

Agreed 👍

---

<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:** [May 16, 2017, 9:28pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/9 "2017-05-16T21:28:03Z")

</div>

I generate markdown code from the source tree, no html. I use mkdocs with  
the material theme. Medics generates the html.

---

<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:** [May 16, 2017, 9:29pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/10 "2017-05-16T21:29:09Z")

</div>

Sorry, mkdocs generates the html.

---

<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:** [May 16, 2017, 9:31pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/11 "2017-05-16T21:31:35Z")

</div>

I see. In your case, the documentation toolchain is `mkdocs` and it outputs the html that is then pushed on GitHub.

Instead of maintaining a build machine yourself, you could have readthedocs taking care of running mkdocs for you. See [http://docs.readthedocs.io/en/latest/builds.html#mkdocs](http://docs.readthedocs.io/en/latest/builds.html#mkdocs)

---

<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:** [May 16, 2017, 9:45pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/12 "2017-05-16T21:45:09Z")

</div>

I’ll take a look at readthedocs and see if it adds value for my app.

How long has readthe docs been around and is it’s future as stable as  
github?

---

<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:** [May 16, 2017, 9:53pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/13 "2017-05-16T21:53:37Z")

</div>

> [@Lorensen](#):
>
> How long has readthe docs been around and is it’s future as stable as  
> github?

Code base has been around for 7 years so far. See [Pulse · readthedocs/readthedocs.org · GitHub](https://github.com/rtfd/readthedocs.org/graphs)

Hosting has been around for 4 years.

From [Pricing - Read the Docs](https://readthedocs.org/sustainability/) :

```auto
Read the Docs has grown substantially since its beginning as a weekend project.
Today, we:

    Serve over 20 million pages of documentation a month
    Have 10 servers and serve over 2 TB of documentation a month
    Host over 18,000 projects and support 25,000 users
    Are supported by two dedicated engineers

```

---

<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:** [May 16, 2017, 10:07pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/14 "2017-05-16T22:07:02Z")

</div>

2 guys… I think I’ll stick with github.

---

<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:** [May 16, 2017, 10:31pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/15 "2017-05-16T22:31:52Z")

</div>

> [@Lorensen](#):
>
> 2 guys…

Sounds good.

One more comment and I will let you make your final call …

- Having two dedicated engineers along with the described resources is (I think) outstanding and a positive and encouraging point 🙂 Also worth noting that Rackspace (who is also [providing the backend storage for GitHub](https://github.com/blog/493-github-is-moving-to-rackspace)) is graciously providing the storage for readthedocs.

- In addition of two dedicated engineers, their are three teams: Support team, operation team and development team. See [Read the Docs team — Read the Docs user documentation](https://docs.readthedocs.io/en/latest/team.html)

- To put things in perspective, there are three (most likely not dedicated and/or volunteer) maintainers for mkdocs. See [Release Notes - MkDocs](http://www.mkdocs.org/about/release-notes/#maintenance-team)

---

<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:** [May 16, 2017, 10:32pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/16 "2017-05-16T22:32:03Z")

</div>

Finally, note that in both case … if you want to serve documentation over https using a custom domain, you will have to setup your own server:

- [http://docs.readthedocs.io/en/latest/alternate\_domains.html#cname-ssl](http://docs.readthedocs.io/en/latest/alternate_domains.html#cname-ssl)
- [https://help.github.com/articles/securing-your-github-pages-site-with-https/](https://help.github.com/articles/securing-your-github-pages-site-with-https/)

---

<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:** [May 16, 2017, 10:36pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/17 "2017-05-16T22:36:59Z")

</div>

Custom domain is very important, as it allows you to change anything (hosting, documentation generator, etc.) without disrupting users or search indexing bots. It is impossible to know what services will still exist in 2-3 years or if there will be much better options you will want to switch to.

---

<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:** [September 10, 2018, 7:25pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/18 "2018-09-10T19:25:49Z")

</div>

it would be nice to start using readthedocs more seriously for Slicer core module documentation. People could just use their GitHub account to contribute (no more wiki signup troubles), we could keep the code and documentation tightly linked, etc.

[Blender manual on ReadTheDocs](https://blender-manual.readthedocs.io/en/latest/#) is a good example of how it could look. It is a huge manual, so most probably we can use the same techniques, we would not need to invent anything new. Its source code is available here: [https://developer.blender.org/diffusion/BM/](https://developer.blender.org/diffusion/BM/)

The main complication right now is that the documentation is generated from a [separate branch](https://github.com/Slicer/Slicer/tree/rst-user-and-dev-guide). Keeping the documentation branch in sync with master is difficult because for example I want to merge changes of `util.py` from master, but some files are only present in the documentation branch.

**Should we maintain code and documentation in same repository and branch?**

Advantages of keeping code and documentation together:

- Documentation and code would be tightly synchronized. We could ensure that even small details, programming examples, etc. are always accurate.
- We could do code and documentation updates in the same pull request (we can better enforce consistency and quality, include documentation testing in continuous integration, etc).
- Documentation and code is kept together in smaller projects anyway, such as in Slicer extensions. We would use the same operating mechanism for Slicer core and extension documentation.
- We can generate user and API documentation from the same repository. User and developer documentation are often interlinked, so it is useful if we can generate them together.

Advantages of keeping documentation in separate repositories:

- Smaller code repository size. Slicer source code size is currently about 110MB. Over time, documentation would probably make it about 50% larger (estimated based on Blender manual, which is 70MB: contains 1900 png files, 1200 rst files).
- Access control and development process could be defined separately for source code and documentation.

I lean towards keeping code and documentation in one repository and branch. What do you think?  
@jcfr @pieper @cpinter @ihnorton @fedorov

---

<div class="post-metadata">

**Author:** ![cpinter](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/cpinter/32/7995_2.png) [@cpinter](https://discourse.slicer.org/u/cpinter)\
**Post date:** [September 10, 2018, 7:42pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/19 "2018-09-10T19:42:20Z")

</div>

I’d strongly prefer having them in the same repository. If we have the documentation in the code then it also will be much harder to forget updating the documentation (you need to realize that it needs to be changed, find the wiki page, upload new screenshot to mediawiki, etc.).

About the disadvantages of the same repository approach, the only one I consider a problem is access. I guess then we’d need a place where anybody can suggest edits, and a person who’s responsible for migrating the suggestions. Neither seem to be an easy problem to solve, but the second one could happen the same way we handle PRs: anyone who has a minute reviewing/integrating does it. Any ideas about how to offer the documentation for editing for the wide public?

---

<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:** [September 10, 2018, 8:44pm UTC](https://discourse.slicer.org/t/document-modules-on-readthedocs/330/20 "2018-09-10T20:44:38Z")

</div>

> [@cpinter](#):
>
> Any ideas about how to offer the documentation for editing for the wide public?

You can edit documentation on the web interface and when you submit your change then a pull request is automatically created. So, documentation changes can be managed the same way as source code change requests. This would require promoting GitHub to be the primary repository (which we plan to do anyway).

[Next page](https://discourse.slicer.org/t/document-modules-on-readthedocs/330.md?page=2)