I would like to know what is the current preferred way to write documentation for a Slicer scripted module?
This page suggest writing a wiki page:
We have requested an account here to do so, but no answer:
https://www.slicer.org/wiki/Special:RequestAccount
Also, I would like to know how to proceed for a new module. Our module is not quite ready yet for publication, but we would like to build the documentation as we go. Is there a way to keep the wiki page private until we publish the module?
The world has changed since that wiki page was created (at that time github did not exist, it was not trivial to get free hosting, render documentation, etc.). I’ll update it.
We are moving software documentation to the source code repository both for Slicer core and for extensions.
For simple documentation, you can put everything in the top-level README.md file in the repository and rely on Github’s default rendering. For more comprehensive documentation you can add more files, use github pages or readthedocs for rendering pages.
I am also on this boat.
Do you have any guidelines about creating the documentation. I found this, Document modules on readthedocs but there isn’t much in it. I am not familiar with readthedocs and how it is pulled from GH. It would be great if someone can point out some Slicer specific examples.
Also, wiki was clunky and while ugly, it had a consistent style across modules. Is the current plan each project doing their own style etc…
some Slicer specific examples.
See Slicer/Docs/user_guide/modules at main · Slicer/Slicer · GitHub
Thanks jc. Is there any other documentaiton about how to link these to readdocs?
I would recommend to start with writing markdown files in Github. Whatever you write, will be usable in readthedocs, too, without any formatting change.
If you end up having dozens of pages of documentation then you can think about how to organize the information better. But I’m not even sure that it is a good approach, as users don’t tend to read lengthy documentation either. Creating more self-explaining modules (using tooltips, wizards, etc.), tutorials (text, slide, or video based), Jupyter notebooks, etc. might be a better time investment than more thorough reference manual.
Read-the-docs is interesting because it is widely used in Python developer community, offers nice navigation between pages, and allows generating documentation using Python (for example, instead of creating screenshots manually, you can run Python code snippets and embed resulting data into the documentation).
We don’t have a good example for an extension with read-the-docs documentation but would be happy to work this out with you (use SlicerMorph as a pilot, then update the extension template based on what we learn).
I like consistency a lot, but I’m afraid it would be hard to enforce it now. Centralized documentation was a good fit when most Slicer development was paid from a center grant. It was also a decade when software development was not as distributed as now (people still used SVN instead of git, Matlab’s centrally managed toolboxes were the norm instead of Python packages provided by hundreds of thousands of developers, etc.).
We could make the Slicer extension manager something similar to the Python Package Index (PyPI) - showing structured metadata and a custom “Project description” page (often the same as the main README.md file of the project).
THanks. We have plenty of markdown for our modules (on our workshop folders) that we can rework into module documentation.