Document modules on readthedocs

Development
1

I quite like the Slicer documentation on readthedocs. 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? Or should I wait for getting this branch merged to master?

2

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.

3

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

I’m experimenting with it here:
https://lorensen.github.io/VTKExamples

4

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

5

Well done. These look quite nice :thumbsup:

6

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

7

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

8

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

  • regular HTML is published
  • jekyll based templates are used

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

Agreed :thumbsup:

9

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

10

Sorry, mkdocs generates the html.

11

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

12

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?

13

Code base has been around for 7 years so far. See Pulse · readthedocs/readthedocs.org · GitHub

Hosting has been around for 4 years.

From Pricing - Read the Docs :

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
14

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

15

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 :slight_smile: Also worth noting that Rackspace (who is also providing the backend storage for GitHub) 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

  • To put things in perspective, there are three (most likely not dedicated and/or volunteer) maintainers for mkdocs. See Release Notes - MkDocs

16

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:

17

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.

1 Like
18

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 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/

The main complication right now is that the documentation is generated from a separate branch. 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

3 Likes
19

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?

20

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

2 Likes