ENH: User and developer guide as RestructuredText **WIP**

[jcfr]

This is a first draft of the user and developer documentation rendered on http://slicer.readthedocs.io

Documentations is organized in two directories

• Docs/user_guide
• Docs/developer_guide

For now, readthedocs will automatically regenerate the documentation each time the branch Slicer/Slicer@rst-user-and-dev-guide is updated.

Configuration files is Docs/conf.py.

After running:

cd Slicer
pip install -r requirements-dcos.txt

on either Windows or Unix, it can locally be generated running:

cd Docs
make html

Notes

• Consider both installing the requirement and running make html from a virtual environment.

• I think sections like News, Image Gallery, Tutorials, Slicer Community, Labs, Developer Hangout, FAQs should probably remain on the wiki.

[cpinter]

Links will be needed here, otherwise the reader won't know what's "this". The links are there on the corresponding wiki page
https://www.slicer.org/wiki/New_users#Tutorials

[cpinter]

Did you use a converter? If so, maybe it would be worth looking into why it stripped out the links

[cpinter]

This is great! Looking forward to have most documentation here!

[cpinter]

I agree with the second bullet in the notes that those pages should remain on the wiki

[fedorov]

Definitely a step in the right direction!

One general issue I have with readthedocs is that the process of contributing a change (or even feedback) to the documentation is quite laborious for non-developers.

Did you consider gitbook?

How do you envision the process of extension documentation? Will the user guide just have a pointer to the external documentation resource for the extension?

[pieper]

We discussed this on the last developer hangout. There was a concern that markdown was not expressive enough and comes in many 'flavors'. Also it seems that rst is not really standard and is tied to the python implementation, but the toolchain is more powerful and customized for documentation.

…

On Tue, Mar 21, 2017 at 12:41 PM, Andrey Fedorov ***@***.***> wrote: Definitely a step in the right direction! One general issue I have with readthedocs is that the process of contributing a change (or even feedback) to the documentation is quite laborious for non-developers. Did you consider gitbook <https://www.gitbook.com>? How do you envision the process of extension documentation? Will the user guide just have a pointer to the external documentation resource for the extension? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <Slicer/Slicer#686 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAHsfTpKZTSfCe1oF8KeBxrTR-iQuZx-ks5rn_3XgaJpZM4Mj-W3> .

[lassoan]

I've spent several days porting existing Slicer documentation pages to both gitbooks and Sphinx/readthedocs to have an idea about their capabilities and limitations. They are both limited compared to mediawiki in term of formatting but storing documentation along with source code and ability to create offline documentation make gitbooks/readthedocs more versatile and sustainable.

I like collaboration features of gitbooks (ability to comment, etc) and availability of markdown editor, but they are not very simple and clear. For example, if doc authors don't have commit rights to the repository then they still have to learn how to create pull requests, etc. Readthedocs can be configured to show edit links on all pages, which makes it very easy to make changes, preview the results, fork the repository, and create a pull request - overall not significantly more complex than gitbooks.

There are two big advantages of Sphinx/readthedocs:

• Sphinx uses restructuredtext. Gitbook's markdown is frustratingly limited compared to mediawiki and requires lots of creativity in figuring out how to convert content.
• It's very easy to set up the doc generation toolchain. Gitbooks is mainly meant to be used online, and although you can set up the toolchain on your own computer, it's very difficult to do it on Windows.

So, overall gitbooks have some slight advantages, overall for me sphinx/readthedocs is the clear winner.

[jcfr]

from Csaba: Did you use a converter? If so, maybe it would be worth looking into why it stripped out the links

I manually added this page. Since some of the link will be internal reference ... I suggest to stabilize the overall organization first.

From Andras: I've spent several days porting existing Slicer documentation pages to both gitbooks and
Sphinx/readthedocs

@lassoan Thanks for the detailed report. Do you have a link pointing to your sphinx experiment ?

From Andras: I like collaboration features of gitbooks (ability to comment, etc) and availability of markdown editor,
but they are not very simple and clear. For example, if doc authors don't have commit rights to the
repository then they still have to learn how to create pull requests, etc. Readthedocs can be
configured to show edit links on all pages, which makes it very easy to make changes, preview the
results, fork the repository, and create a pull request - overall not significantly more complex than
gitbooks.

From Andrey: One general issue I have with readthedocs is that the process of contributing a change

Here is a comparison of both gitbook and readthedocs contribution process: https://www.slicer.org/wiki/Documentation/Labs/DocumentationImprovments#Proposing_changes

Note that, in both case, the user would have to create a GitHub account.

From Andrey: (or even feedback) to the documentation is quite laborious for non-developers.

Readthedocs doe not include a comment section

Regarding gitbook, I just realized you could comment on block of text in gitbook. It wasn't easy to discover ...

While we have the possibility to comment on mediawiki (using the Talk) page, this is not something we have been using.

Did you consider gitbook?

Based on feedback of @lassoan , use of markdown is limiting.

How do you envision the process of extension documentation?

We could provide a cookiecutter template and let extension maintainer document their project will complete autonomy, we could for example include a docs folder in the extension templates.

Will the user guide just have a pointer to the external documentation resource for the extension?

Indeed, I am thinking about a simple list of extensions alphabetically listed. I will include a mockup.

[ihnorton]

Do we really need all features? I think ReST is attractive for a programmer mindset, but relatively user-unfriendly (both the styling itself, and the workflow). If we want users to contribute to documentation, it's better not to optimize for programmer convenience. ReST has too many foot-guns in my experience: particular about easy-to-miss details, doesn't degrade gracefully, even creating links is annoying.

[lassoan]

Unfortunately, users don't make any significant contribution to documentation. The wiki made it very simple, still it did not happen. Have a look at https://www.slicer.org/w/index.php?title=Special:RecentChanges&days=300&from=&limit=2500
Most changes are made by core and extension developers. Changes from "users" were minor changes/additions, that can be easily managed directly on the github web GUI.

@ihnorton What is your suggestion as an alternative to ReST? Markdown?

[jcfr]

Additionally, without a way to review changes proposed on the wiki we have been very conservative to activate the wiki account creation. There is current a significant queue of account being "on hold".

[ihnorton]

Markdown?

Yes. I've used both fairy extensively, and prefer Markdown. Point taken about user contributions, but on the other hand there is a fair amount of documentation-adjacent content (e.g. powerpoint tutorials) created by non-programmers -- partly created that way because the Wiki wasn't actually all that accessible (how many steps are required to upload an image; Wiki server was painfully slow and not upgraded for years; parallel documentation versions were confusing, etc.).

Either one will be an improvement, of course (and Jc's rendered version looks great!), but $.02 if the decision is still pending.

[jcfr]

Nothing is written in stone yet.

Worth nothing that github markdown has been formalized https://githubengineering.com/a-formal-spec-for-github-markdown/

upload an image

We need to explore this a little bit more. I currently added link to external images. As we need contributor (non developer) to potentially be able include or update images ... more experiments are required.

Structure

Independently of markdown, RST, .... I would like us to converge to a nice organization of the different sections ...

Yes. I've used both fairy extensively, and prefer Markdown

@ihnorton Do you have example of developer and user documentation written in markdown ?

I suggest we compile a list of application, SDK, libraries documentation to inspire from. For example:

• http://blender-manual.readthedocs.io
• http://doc.qt.io/qtcreator/index.html

While I am not a fan (yet), we could also get the best of both world:

• User guide in markdown available as either slicer.gitbooks.io/user-manual or slicer-user-manual.readthedocs.io

• developer guide + design doc + API references in RestructedText available as slicer-developer-manual.readthedocs.io

slicer.readthedocs.io would then have pointer to one of the other ...

[ihnorton]

example of developer and user documentation written in markdown

http://flight-manual.atom.io/ (graphical, user-oriented; built with nanoc)
https://juliaplots.github.io (user-ish but has code; built by MkDocs)
http://docs.julialang.org/en/stable/ (dev-oriented; built by custom processor)

While I am not a fan (yet), we could also get the best of both world: [...]

👎 whatever is done, please don't mix.

[pieper]

After reading more I have to say I'm feeling like Markdown is preferable. There are more language choices and good implementations (C, JS) while rst seems to be only python.

…

On Tue, Mar 21, 2017 at 4:45 PM, Isaiah ***@***.***> wrote: example of developer and user documentation written in markdown http://flight-manual.atom.io/ (graphical, user-oriented; built with nanoc) https://juliaplots.github.io (user-ish but has code; built by MkDocs) http://docs.julialang.org/en/stable/ (dev-oriented; built by custom processor) While I am not a fan (yet), we could also get the best of both world: [...] 👎 whatever is done, please don't mix. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <Slicer/Slicer#686 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAHsfX9PON_C_6H1KxUFT3NkE4OodBiuks5roDbngaJpZM4Mj-W3> .

[fedorov]

I am not at all saying that gitbook is perfect, but you have to admit that it provides way more user friendly editor compared to alternatives, and they have more streamlined mechanism for the user to suggest edits or provide feedback without the need to do actual edits, so the contribution threshold is lower.

I get the point of Andras about lack of outside contributions, but it is impossible to parse out what combination of factors caused this - confusing organization of documentation, users not reading documentation, non-friendly sign-up mechanism, geeky formatting of the wiki, or lack of interest in contributing.

[lassoan]

Markdown has so many variants because the basic feature set is so limited that everybody tries to find a way out somehow. So, Markdown as such is not really an option, but we have to actually choose a specific Markdown flavor and toolchain.

@ihnorton Which flavor, preprocessor/generator, and hosting platform do you think would be suitable for both Slicer user and developer documentation?

[fedorov]

FYI gitbook has a simplified contribution workflow that is supposed to bypass the PR process (I have not tested this) https://help.gitbook.com/books/what-are-change-requests.html. Currently this feature is available only to the collaborators on the book, but they plan to roll it out to be accessible for the "readers" who are not part of the organization.

[lassoan]

While github supports both ReST and Markdown, Discourse only supports Markdown. It would be important not to force community members to learn multiple markups.

[jcfr]

It would be important not to force community members to learn multiple markups.

That said, with the embedded editor provided in these platforms (github, discourse, ...) ... I do not think it is an issue and user can easily discover and re-discover how to write comments.

I did few more experiments and it is quite easy to:

• convert between to/from mardown to/from rst. This means while we are moving forward with the experiment, we can easily go from one format to an other. See 8167b55 for an example

• support both markdown and RestructuredText: I enabled the recommonmark parser, this means that markdown can be used. For example, this page is originally written in markdown.

That said,

• documentation related to developer build system, Python and Cpp API will most likely be in restructured text. There is a great support for python code, support for documentation CMake code (see here), and an available integration with doxygen using breathe (still need to experiment)

And finally here some more experiments do do:

• upload of image for non developer.
• look into asciidoc (what is used to write oreilly books and is recommended when a robust features set is needed while keeping wiki like format). Here is an example of book: https://github.com/progit/progit2
• look into use of breathe for integrating doxygen
• look into creation of image/example/... gallery using md, rst, ...

Updates on gitbooks:

• asciidoc is supported on gitbook
• can be extended using plugin

[jcfr]

• Uploading images as a non developer by only using the GitHub interface is a cumbersome process. See https://www.slicer.org/wiki/Documentation/Labs/DocumentationImprovments#ReadTheDocs_.2F_GitHub

• gitbook:

  • free for opensource project BUT the number of collaborator with write access is limited to 5. Unless we can get unlimited access, it will not allow to accept contribution.

  • that said by setting the Github synchronization, we would still virtually get unlimited contributor with the other nice features of gitbook (analytics, comment, etc ....):

    • Test to confirm updates done on Github by non collaborator are propagated

[jcfr]

From http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

[Markdown] is great for a subset of tasks, mainly blog posts and commenting.

As documentation grows from a few pages into a large set of documents, Markdown quickly falls
over and becomes a liability instead of a benefit.

Lack of a standard: ...
Flavors ...
Lack of Extensibility: ...
Lack of Semantic Meaning: ....
Lock In and Lack of Portability: ...

Disclaimer: [author] work on a product, Read the Docs, which is based on Sphinx, so [author] views are likely biased.

[fedorov]

free for opensource project BUT the number of collaborator with write access is limited to 5. Unless we can get unlimited access, it will not allow to accept contribution.

also note that we can get "open source" plan for the Slicer organization that can bump the number of collaborators up to 10 at least (I did not try to ask for an unlimited plan) - I already did this for the QIICR organization: https://www.gitbook.com/pricing.

But as you pointed out, the standard PR request approach directly via github is unlimited, and also if they stick to their promise to roll out change requests to the contributors outside the team, this will not be an issue at all.

[jcfr]

can bump the number of collaborators up to 10 at least

Very nice. Here is a draft of email asking them if they could grant us unlimited access for the Slicer community:

Subject: Increase # contributor limit for 3D Slicer open-source organization

Dear Gitbook team, 

Thanks for both maintaining this awesome project and also offering for free it for open-source project. This is great.

The Slicer community, whom I represent here, is evaluating Gitbook as an outlet for publishing its 
user manual(s) associated with 3D Slicer. 

3D Slicer is an open source software platform for medical image informatics, image processing, and
three-dimensional visualization. It has been downloaded more than 250K times in past 5 years (with 
a current download rate of 300 per day) and is used in more than 18 countries. 

To effectively support our community, we would like to allow contributor from all other the world to
submit change requests to our manuals. To allow this, we were wondering if you could bump the
number of contributors limit to a larger number. Unlimited would be ideal.

Thanks for considering, 
Jc

Let me know what you think.

their promise to roll out change requests

That is neat.

That said, it is mentioned that All collaborators with edit access can create a change request from the GitBook Editor.

[cpinter]

I think the argument about one syntax being harder than another is not entirely valid, because everybody copy-pastes sections like tables, links, etc. Honestly, who knows how to add a file likk in MediaWiki, even years after using it? I don't :) I copy-paste. So I think we shouldn't decide based on this.

Also we should consider how versatile the created document is. As far as I know (not from personal experience), RST can do more things in terms of tables, image captions, formatting, etc. If it's not important, and we shoot for the simplest style, then it doesn't matter, but in some cases formatting within tables are really helpful.
Is there a markdown flavor that has significantly extended formatting options and is not expected to be deprecated in the next decade or so?

10 contributors is still basically nothing if we want to allow outsiders to edit, then we need more, unless we can create an "anonymus slicer doc editor" git account (maybe not). That said, change requests should not be a big barrier, especially if someone has done at least one already (some people are afraid of new processes).

[fedorov]

@jcfr the draft looks great! If you don't hear for some time after you send it, we should ping them on slack. My request was pending for a very long time, because they have a small team relative to the user base.

That said, it is mentioned that All collaborators with edit access can create a change request from the GitBook Editor.

Yes, right, this is the currently available feature. I was referred to their plan to (eventually) make the process of contribution similarly simple for non-collaborators.

[fedorov]

Do we have a table that would summarize features/advantages/issues between ReadTheDocs and GitBook? I have not hear any other viable options, so perhaps putting together that table (using the powerful MediaWiki formatting syntax! ;-D ) is a good next step.

[ihnorton]

@lassoan I like gitbooks and MkDocs.
That said, I'm not doing the work here, and I'd prefer this move forward with RST if that's what @jcfr and @lassoan like, instead of getting bogged down in choice paralysis. Please just try to make the workflow have minimum steps (in the past I've had to make a PR in order to get any validation or even preview, then update the PR for mistakes, etc. maybe Github RST preview is good enough now to avoid this).

Other request would be for user manual to be in a separate repo

• checking in images (binary data) will make the main Slicer repo more unwieldy.
• we can go directly to a Github workflow for the manual, regardless of the timeline for svn->git transition for the source repo.

[fedorov]

That said, I'm not doing the work here, and I'd prefer this move forward with RST if that's what @jcfr and @lassoan like, instead of getting bogged down in choice paralysis.

I completely agree. It is not my intent to stall this either, I just wanted to make sure that all involved in the decision making process are aware of the options and potential issues. But I also think that preparing a table with the summary of the pros and cons, and presenting that as the background work for the wider community as the motivation for the final decision is good and consistent with the decision making policy we discussed in January.

Personally, if I had to choose between keeping the current wiki documentation and switching to RST/ReadTheDocs, I would definitely choose the latter.

[lassoan]

Git-lfs is not ready for prime time yet. So, we should probably just add all documentation files as regular files to the repository.

[superlib]

I'm getting 404s for all of the images linked from the Getting Started Guide at https://slicer.readthedocs.io/en/latest/user_guide/getting_started.html

Additionally on that page, the list under 'Tutorials' looks like it should have links, but doesn't:

• To learn about using Slicer for 3D Printing, visit this tutorial.
• To learn about Neurosurgical Planning with Slicer, visit this tutorial.
• To learn about DTI, visit this tutorial.

[jcfr]

Thanks for pointing this out 🙏

We will fix this shortly.

[jcfr]

Closing. Changes integrated into Slicer/Slicer#4771