Difference between revisions of "Documentation/Labs/DocumentationImprovments"

From Slicer Wiki
Jump to: navigation, search
 
(37 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
__TOC__
 
__TOC__
  
−
== Websites ==
 
  
−
=== slicer.org ===
 
−
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1967 1967]: Improve "slicer.org" page - Easier access to build / download / contribute</s>
 
  
−
=== download.slicer.org ===
+
== Experiments ==
  
−
* <s>[http://www.na-mic.org/Bug/view.php?id=1966 1966]: Add disclaimer associated with 32bit on download.slicer.org</s>
+
=== User manual with GitBook ===
−
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1991 1991]: Cosmetics for the slicer download page</s>
 
  
−
== Mediawiki: wiki.slicer.org ==
+
See https://www.gitbook.com/
  
−
{{remark|green|Issue reports and feature requests can be listed using this link: <br>http://tinyurl.com/zzssdfb}}
+
* Segment-editor: https://lassoan.gitbooks.io/test-book/content/modules/segment-editor/
 +
* SliceTracker: https://fedorov.gitbooks.io/slicetracker/content/
 +
* DCMQI: https://fedorov.gitbooks.io/dcmqi/content/
  
−
=== Infrastructure ===
+
=== Improved Wiki User Documentation ===
  
−
* [http://www.na-mic.org/Bug/view.php?id=2971 2971]: Install MetaTags extension
+
This page is being developed by Hillary from Queen University with help from Andras Lasso.
−
** Would be great to try it. Note that dependent extension [https://www.mediawiki.org/wiki/Extension:StubManager StubManager] is not maintained anymore
 
  
−
* [http://www.na-mic.org/Bug/view.php?id=1543 1543]: Install CategoryTree extension
+
It is based on [http://hillarys-mockup.wikia.com/wiki/Hillary%27s_Mock-up_Wikia this mock-up] and is intended to become the new Slicer landing page.
−
* [http://www.na-mic.org/Bug/view.php?id=2190 2190]: Fix graphviz installation on Slicer wiki
 
−
* [http://www.na-mic.org/Bug/view.php?id=2170 2170]: Install extension SyntaxHighlight_GeSHi on Slicer wiki
 
  
−
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=2272 2272]: Simplfy the first screen of the Slicer documentation page</s>
+
* [[New users]] page
  
−
* [http://www.na-mic.org/Bug/view.php?id=2968 2968]: Slicer wiki - Enable short url => easier configuration of robots.txt
+
== Discussions ==
  
−
* Account
+
=== New front page for Slicer.org ===
−
** [http://www.na-mic.org/Bug/view.php?id=4216 4216]: Wiki: Notify Slicer core developers
 
−
 
 
−
* Variables extension:
 
−
** https://www.mediawiki.org/wiki/Extension:Variables
 
−
** http://slicer-devel.65872.n3.nabble.com/Re-slicer-users-slicer-na-mic-web-stuff-upgraded-some-things-broken-this-morning-tp4035767p4035777.html
 
−
 
 
−
* Analytics
 
−
** [http://www.na-mic.org/Bug/view.php?id=4215 4215]: Notify Slicer core developers when an account is created
 
−
 
 
−
* Improved UI
 
−
** [http://www.na-mic.org/Bug/view.php?id=4214 4214]: Wiki: Add support for vectorial fonts
 
−
 
 
−
* Widgets extension:
 
−
** https://www.mediawiki.org/wiki/Extension:Widgets
 
−
** http://slicer-devel.65872.n3.nabble.com/Re-slicer-users-slicer-na-mic-web-stuff-upgraded-some-things-broken-this-morning-tp4035767p4035778.html
 
−
* YouTube extension:
 
−
** https://www.mediawiki.org/wiki/Extension:YouTube
 
−
* Google Calendar
 
−
** https://www.mediawiki.org/wiki/Extension:GoogleCalendar
 
  
−
=== Improvements ===
+
* Evaluating transition of front page to a more collaborative platform. Few options:
 +
** Mediawiki Visual editor for front page
 +
** GitHub based static pages. Experiment stored [https://github.com/Slicer/slicer.org here]
  
−
==== User documentation ====
+
* Current workflow:
 +
** Update are performed by Marianna
  
−
This page is being developed by Hillary from Queen University with help from Andras Lasso.
+
* What is the role of the front page ?
 +
** Easy to digest introduction to help decide with they would like to move forward
 +
** Appealing, well designed, "modern" looking
 +
** Page we need to "proud of" .. it show case all the great work done in the backend.
 +
** Well integrated with search engine (SEO). This is also coupled with user/developer documentation.
 +
** Given new user guidance ?
  
−
It is based on [http://hillarys-mockup.wikia.com/wiki/Hillary%27s_Mock-up_Wikia this mock-up] and is intended to become the new Slicer landing page.
+
* Nice example of a front page for a project: https://robomongo.org/
  
−
* [[New users]] page
+
=== Improved FAQ ===
 +
* Spreadsheet about mailing list questions: [[File:UsersMailingListSlicer4.5.xlsx]] (between 2015.11. and 2016.07., by Hillary Lia)
  
−
== Transition to a new platform ==
+
== New Platform: Requirements ==
  
 
=== Expected features ===
 
=== Expected features ===
Line 79: Line 64:
 
** authentication integrated with commonly used services (google, github,...)
 
** authentication integrated with commonly used services (google, github,...)
 
** prominent visibility of the Slicer web/doc resources on google (related issue: http://www.na-mic.org/Bug/view.php?id=3938)
 
** prominent visibility of the Slicer web/doc resources on google (related issue: http://www.na-mic.org/Bug/view.php?id=3938)
 +
** Check and report dead links
  
 
* User
 
* User
Line 103: Line 89:
  
 
* user feedback: https://hypothes.is
 
* user feedback: https://hypothes.is
 +
 +
* FAQ: dedicated github repo as done here: https://github.com/ipfs/faq ? Benefits:
 +
** search is potentially easier
 +
** easy to insert images and format content
 +
** users can vote on FAQ entries
 +
** labels can be added to categorize entries
 +
** github API can be used (I am assuming!) to pull this and render a web-page, after the FAQ entry has been worked on and finalized by the community
 +
 +
== New Platform: Comparison ==
 +
 +
 +
=== Summary ===
 +
 +
==== Legend ====
 +
 +
{| class="wikitable feature_compare_table"
 +
! Very Easy
 +
| class="veryeasy"    | builtin feature, minimal setup
 +
| <code>class="veryeasy"</code>
 +
|-
 +
! Easy
 +
| class="easy"| simple install, simple script or cron job
 +
| <code>class="easy"</code>
 +
|-
 +
! Moderate
 +
| class="moderate"| involved development, advanced setup, not streamlined
 +
| <code>class="moderate"</code>
 +
|-
 +
! Difficult
 +
| class="difficult"| Not available, doesn't make sense, very involved hackery
 +
| <code>class="difficult"</code>
 +
|}
 +
 +
 +
==== How these tables where created ? ====
 +
 +
# Mockup table using http://www.tablesgenerator.com/mediawiki_tables
 +
# Add new css classes at the end of [[MediaWiki:Common.css]]
 +
# Assign a rating to each cell
 +
 +
Note that table layout can also easily be generated using the built-in table generator:
 +
 +
[[File:Mediawiki-builtin-table-generator.png|400px]]
 +
 +
==== List of features for each platforms ====
 +
 +
{| class="wikitable feature_compare_table"
 +
!
 +
! MediaWiki
 +
! ReadTheDocs + Sphinx
 +
! Gitbook + GitHub
 +
|-
 +
| Sign-up for contributor account
 +
| class="difficult" | Dedicated Account
 +
| class="veryeasy"  | Github Account
 +
| class="veryeasy"  | Github Account
 +
|-
 +
| From Web: Create a new page
 +
| class="veryeasy"  | Easy
 +
| class="easy"      | Moderate (step 1, create file, step 2, update index)
 +
| class="veryeasy"  | Easy (using "Add Article")
 +
|-
 +
| From Web: Edit exiting page
 +
| class="veryeasy"  | Easy
 +
| class="veryeasy"  | Easy
 +
| class="veryeasy"  | Easy
 +
|-
 +
| From Web: Edit exiting page uploading images
 +
| class="easy"      | Easy (Click upload link, select image, confirm)
 +
| class="moderate"  | Not straighforward, a lot of steps
 +
| class="veryeasy"  | Easy (Click upload, Drag'n drop, Confirm)
 +
|-
 +
| From Web: Preview local changes
 +
| class="veryeasy"  | Easy
 +
| class="veryeasy"  | Easy
 +
| class="veryeasy"  | Easy
 +
|-
 +
| From Web: Preview changes for complete website
 +
| class="difficult" | NA
 +
| class="veryeasy"  | No (or difficult would need to deploy topic/PR in dedicated github page)
 +
| class="veryeasy"  | Yes
 +
|-
 +
| Changes available in Git
 +
| class="difficult" | No (or very difficult to setup)
 +
| class="veryeasy"  | Yes
 +
| class="easy"      | Yes (through sync mechanism, conflict could happen)
 +
|-
 +
| Preview changes on workstation
 +
| class="difficult" | NA
 +
| class="easy"      | Yes (1) setup virtual env, then make.bat, make, (2) Potentially provide toolchain as a Slicer extension
 +
| ??
 +
|-
 +
| Support update pushed on GitHub
 +
| class="difficult" | No
 +
| class="veryeasy"  | Yes
 +
| class="easy"      | Yes (through sync mechanism, conflict could happen)
 +
|-
 +
| Possibility to review changes
 +
| class="easy"      | Only afterward
 +
| class="veryeasy"  | Yes (with Pull Request)
 +
| class="veryeasy"  | Yes (with Change Request)
 +
|-
 +
| Manage documentation version
 +
| class="difficult" | Difficult
 +
| class="veryeasy"  | Easy
 +
| ??
 +
|-
 +
| Allow reader to annotate
 +
| class="moderate"  | No
 +
(or through https://hypothes.is/)
 +
| class="moderate"  | No
 +
(or through https://hypothes.is/)
 +
| class="veryeasy"  | Yes - Built in
 +
|-
 +
| Allow reader to comment on page
 +
| class="easy"      | Yes
 +
Talk page (Not used in practice)
 +
| class="difficult" | No
 +
| class="veryeasy"  | Yes
 +
|-
 +
| Formatting tables
 +
| class="easy"  | Yes (using [http://www.tablesgenerator.com/mediawiki_tables www.tablesgenerator.com]
 +
| class="easy"  | Yes (using [http://www.tablesgenerator.com/mediawiki_tables www.tablesgenerator.com]
 +
| class="veryeasy"  | Yes (using builtin table editor)
 +
|-
 +
| Support table sorting
 +
| class="veryeasy"  | Easy (builtin css class + js)
 +
| class="moderate"  | Yes (To be added to js and css)
 +
| class="moderate"  | Yes (To be added to js and css)
 +
|-
 +
| Automatic TOC generation
 +
| class="veryeasy"  | Yes
 +
| class="veryeasy"  | Yes
 +
| class="veryeasy"  | Yes
 +
|-
 +
| Cross-referencing section
 +
| class="veryeasy"  | Yes
 +
| class="veryeasy"  | Yes
 +
| ??
 +
|-
 +
| Link to existing documentation (Qt, VTK, ...)
 +
| class="veryeasy"  | Using direct link
 +
| class="veryeasy"  | Using direct link (or intersphinx)
 +
| class="veryeasy"  | Using direct link
 +
|-
 +
| Sharing link to page section
 +
| class="veryeasy"  | Yes
 +
After clicking on TOC entry at the top
 +
| class="veryeasy"  | Yes
 +
Anchor available near section title
 +
| class="veryeasy"  | Yes
 +
After clicking on TOC entry on  the right
 +
|-
 +
| Cross-platform generation toolchain
 +
| class="difficult" | Not available
 +
| class="veryeasy"  | Yes
 +
| ??
 +
|-
 +
| Indexing by search engine
 +
| class="difficult" | Difficult, involve tweaking page headers, updating robots.txt, ...
 +
| ??
 +
| ??
 +
|-
 +
| Analytics
 +
| class="moderate"  | Possible with Google analytics (with [https://www.mediawiki.org/wiki/Extension:Google_Analytics_Integration Extension:Google_Analytics_Integration]
 +
| class="veryeasy"  | Builtin support for Google analytics
 +
| class="easy"      | Built-in (but no per page stats)
 +
|-
 +
| Extensible using plugin
 +
| class="moderate"  | Server side extension
 +
| class="easy"      | Toolchain plugins
 +
| class="easy"      | Toolchain plugins
 +
|-
 +
| Local testing of plugin
 +
| class="difficult" | NA
 +
| class="easy"      | update "conf.py" and python import
 +
| ???
 +
|-
 +
| Reference Github user
 +
| class="easy"      | Direct link
 +
| class="easy"      | Direct link
 +
| class="easy"      | Direct link
 +
|-
 +
| Reference Github issue
 +
| class="easy"      | Direct link
 +
| class="easy"      | Using sphinx_issues extension
 +
| class="easy"      | Direct link
 +
|-
 +
| Reference Github commit
 +
| class="easy"      | Direct link
 +
| class="easy"      | Direct link
 +
| class="easy"      | Direct link
 +
|-
 +
| Code Syntax Highlight
 +
| class="easy"      | Yes (with [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight Extension:SyntaxHighlight])
 +
| class="veryeasy"  | Yes
 +
| class="veryeasy"  | Yes
 +
|-
 +
| Maintaining embedded code snippet
 +
| class="difficult" | Code is copied - Hard to maintain (automatic publication could be done using API)
 +
| class="veryeasy"  | Easy - By including tested source file using [http://www.sphinx-doc.org/en/stable/markup/code.html#includes include] directive
 +
| ??
 +
|-
 +
| Document python API
 +
| class="difficult" | No (or very difficult)
 +
| class="easy"      | Easy - Using sphinx-apidoc and python domain directive
 +
| ??
 +
|-
 +
| Document python wrapped VTK-based classes
 +
| class="difficult" | No (or very difficult)
 +
| class="easy"      | Moderate
 +
(using sphinx-apidoc, downloading latest version)
 +
| ??
 +
|-
 +
| Document pythonQt wrapped Qt -based classes
 +
| class="difficult" | No (or very difficult)
 +
| class="difficult" | Hard
 +
(running sphinx api-doc from within Slicer) - **Need to experiment**
 +
| ??
 +
|-
 +
| Document CMake API
 +
| class="difficult" | No (or very difficult)
 +
| class="easy"      | Easy - using sphinx cmake extension
 +
| ??
 +
|-
 +
| Document Cpp API generated from Doxygen
 +
| class="difficult" | No (or very difficult)
 +
| To be tested - Using doxygen + breathe sphinx extension
 +
| ??
 +
|}
 +
 +
=== Proposing changes ===
 +
 +
==== GitBook ====
 +
 +
<gallery widths=500px heights=300px perrow=3>
 +
File:Gitbook-edit-step1.png|1. Click Edit link
 +
File:Gitbook-edit-step2.png|2. Fork
 +
File:Gitbook-edit-step3.png|3. Edit and propose changes
 +
</gallery>
 +
 +
==== ReadTheDocs ====
 +
 +
<gallery widths=500px heights=300px perrow=3>
 +
File:Rtd-edit-step1.png|1. Click "Edit the source" link
 +
File:Rtd-edit-step2.png|2. Click Edit link
 +
File:Rtd-edit-step3.png|3. Edit and propose changes
 +
</gallery>
 +
 +
=== Uploading Images ===
 +
 +
==== ReadTheDocs / GitHub ====
 +
 +
<gallery widths=500px heights=300px perrow=3>
 +
File:Gh-upload-image-1.png|1. Edit source, browse to images folder and click upload files
 +
File:Gh-upload-image-2.png|2. Drag and drop image(s)
 +
File:Gh-upload-image-3.png|3. Type commit message, select create a new branch and click "Propose Changes"
 +
File:Gh-upload-image-4.png|4. Type PR name and click "Create Pull Request"
 +
File:Gh-upload-image-5.png|5. Browse to the branch created on your fork and select the file to edit
 +
File:Gh-upload-image-6.png|6. Edit file and reference image uploaded in previous commit
 +
</gallery>
 +
 +
=== Diff'ing Changes ===
 +
 +
====  ReadTheDocs / GitHub ====
 +
 +
 +
<gallery widths=500px heights=300px perrow=3>
 +
File:Github-diffing-changes.png|Visual diff for markdown and reStructuredText. Note that special directive are not rendered
 +
</gallery>
 +
 +
==== Gitbook ====
 +
 +
<gallery widths=500px heights=300px perrow=3>
 +
File:Gitbook-diffing-changes.png|Visual diff for markdown.
 +
</gallery>
 +
 +
 +
=== Documenting Slicer APIs ===
 +
 +
There are 4 types of object to document:
 +
* pure python classes
 +
* python wrapped VTK classes
 +
* pythonqt wrapped Qt classes
 +
* c++ classes
 +
 +
==== ReadTheDocs / GitHub ====
 +
 +
===== pure python classes =====
 +
 +
List of automodules directives is generated using `sphinx-apidoc`. List can be updated re-running  `sphinx-apidoc` or by manually adding entries.
 +
 +
An entry look like:
 +
 +
<syntaxhighlight lang="rst">
 +
slicer.cli module
 +
-----------------
 +
 +
.. automodule:: slicer.cli
 +
    :members:
 +
    :undoc-members:
 +
    :show-inheritance:
 +
</syntaxhighlight>
 +
 +
 +
===== python wrapped VTK classes =====
 +
 +
Documentation for these classes can also automatically be generated using '''sphinx-apidoc''' and '''automodule''' directive.
 +
 +
Locally, I experimented by updating '''LD_LIBRARY_PATH''' and '''PYTHONPATH''' with Slicer paths but made sure to exclude OpenSSL and Slicer built-in python.
 +
 +
That allow to generate the documentation for vtkITK, teem, .... See below for an example:
 +
 +
[[File:Rtd-vtk-python-wrapped.png|500px]]
 +
 +
===== pythonqt wrapped Qt classes =====
 +
 +
To be done
 +
 +
===== c++ classes =====
 +
 +
Doxygen is currently doing a good job extracting and generating documentation.
 +
 +
== Current platform: Issues and features ==
 +
 +
=== slicer.org ===
 +
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1967 1967]: Improve "slicer.org" page - Easier access to build / download / contribute</s>
 +
 +
=== download.slicer.org ===
 +
 +
* <s>[http://www.na-mic.org/Bug/view.php?id=1966 1966]: Add disclaimer associated with 32bit on download.slicer.org</s>
 +
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1991 1991]: Cosmetics for the slicer download page</s>
 +
 +
=== Mediawiki: wiki.slicer.org ===
 +
 +
{{remark|green|Issue reports and feature requests can be listed using this link: <br>http://tinyurl.com/zzssdfb}}
 +
 +
==== Infrastructure ====
 +
 +
 +
* [http://www.na-mic.org/Bug/view.php?id=2971 2971]: Install MetaTags extension
 +
** Would be great to try it. Note that dependent extension [https://www.mediawiki.org/wiki/Extension:StubManager StubManager] is not maintained anymore
 +
 +
* [http://www.na-mic.org/Bug/view.php?id=1543 1543]: Install CategoryTree extension
 +
* [http://www.na-mic.org/Bug/view.php?id=2190 2190]: Fix graphviz installation on Slicer wiki
 +
* [http://www.na-mic.org/Bug/view.php?id=2170 2170]: Install extension SyntaxHighlight_GeSHi on Slicer wiki
 +
 +
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=2272 2272]: Simplfy the first screen of the Slicer documentation page</s>
 +
 +
* [http://www.na-mic.org/Bug/view.php?id=2968 2968]: Slicer wiki - Enable short url => easier configuration of robots.txt
 +
 +
* Account
 +
** [http://www.na-mic.org/Bug/view.php?id=4216 4216]: Wiki: Notify Slicer core developers
 +
 +
* Variables extension:
 +
** https://www.mediawiki.org/wiki/Extension:Variables
 +
** http://slicer-devel.65872.n3.nabble.com/Re-slicer-users-slicer-na-mic-web-stuff-upgraded-some-things-broken-this-morning-tp4035767p4035777.html
 +
 +
* Analytics
 +
** [http://www.na-mic.org/Bug/view.php?id=4215 4215]: Notify Slicer core developers when an account is created
 +
 +
* Improved UI
 +
** [http://www.na-mic.org/Bug/view.php?id=4214 4214]: Wiki: Add support for vectorial fonts
 +
 +
* YouTube extension:
 +
** https://www.mediawiki.org/wiki/Extension:YouTube
 +
 +
===== Google Calendar =====
 +
* Google Calendar
 +
** <s>https://www.mediawiki.org/wiki/Extension:GoogleCalendar</s> This extension has not been maintained in some time, and no longer supports recent releases of MediaWik
 +
** Instead the following extension could be installed: https://www.mediawiki.org/wiki/Extension:Widgets
 +
 +
* Widgets extension:
 +
** https://www.mediawiki.org/wiki/Extension:Widgets
 +
** http://slicer-devel.65872.n3.nabble.com/Re-slicer-users-slicer-na-mic-web-stuff-upgraded-some-things-broken-this-morning-tp4035767p4035778.html

Latest revision as of 23:27, 22 March 2017

Home < Documentation < Labs < DocumentationImprovments

This page keeps track of possible improvement related to the Slicer documentation infrastructure.


Experiments

User manual with GitBook

See https://www.gitbook.com/

Improved Wiki User Documentation

This page is being developed by Hillary from Queen University with help from Andras Lasso.

It is based on this mock-up and is intended to become the new Slicer landing page.

Discussions

New front page for Slicer.org

  • Evaluating transition of front page to a more collaborative platform. Few options:
    • Mediawiki Visual editor for front page
    • GitHub based static pages. Experiment stored here
  • Current workflow:
    • Update are performed by Marianna
  • What is the role of the front page ?
    • Easy to digest introduction to help decide with they would like to move forward
    • Appealing, well designed, "modern" looking
    • Page we need to "proud of" .. it show case all the great work done in the backend.
    • Well integrated with search engine (SEO). This is also coupled with user/developer documentation.
    • Given new user guidance ?

Improved FAQ

New Platform: Requirements

Expected features

  • Common
    • Analytics
    • Searchable
    • Integrated with C++ and python documentation generator
    • Hackable
    • Easily editable by reader with review process
    • Embed images
    • Embed python and c++ example
    • Link to original documentation for Qt, VTK, ITK, SimpleITK, python
    • Up/Down vote by user ?
    • Collect feedback ?
    • versioning history
    • authentication integrated with commonly used services (google, github,...)
    • prominent visibility of the Slicer web/doc resources on google (related issue: http://www.na-mic.org/Bug/view.php?id=3938)
    • Check and report dead links
  • User
    • Tutorials
    • User Guide
  • For developer
    • Cookbook
    • Reference API

Options

  • gitbook:
  • doxygen:
  • sphinx:
  • sphinx + readthedocs:
  • sphinx + readthedocs + doxygen:
  • mediawiki:
  • FAQ: dedicated github repo as done here: https://github.com/ipfs/faq ? Benefits:
    • search is potentially easier
    • easy to insert images and format content
    • users can vote on FAQ entries
    • labels can be added to categorize entries
    • github API can be used (I am assuming!) to pull this and render a web-page, after the FAQ entry has been worked on and finalized by the community

New Platform: Comparison

Summary

Legend

Very Easy builtin feature, minimal setup class="veryeasy"
Easy simple install, simple script or cron job class="easy"
Moderate involved development, advanced setup, not streamlined class="moderate"
Difficult Not available, doesn't make sense, very involved hackery class="difficult"


How these tables where created ?

  1. Mockup table using http://www.tablesgenerator.com/mediawiki_tables
  2. Add new css classes at the end of MediaWiki:Common.css
  3. Assign a rating to each cell

Note that table layout can also easily be generated using the built-in table generator:

Mediawiki-builtin-table-generator.png

List of features for each platforms

MediaWiki ReadTheDocs + Sphinx Gitbook + GitHub
Sign-up for contributor account Dedicated Account Github Account Github Account
From Web: Create a new page Easy Moderate (step 1, create file, step 2, update index) Easy (using "Add Article")
From Web: Edit exiting page Easy Easy Easy
From Web: Edit exiting page uploading images Easy (Click upload link, select image, confirm) Not straighforward, a lot of steps Easy (Click upload, Drag'n drop, Confirm)
From Web: Preview local changes Easy Easy Easy
From Web: Preview changes for complete website NA No (or difficult would need to deploy topic/PR in dedicated github page) Yes
Changes available in Git No (or very difficult to setup) Yes Yes (through sync mechanism, conflict could happen)
Preview changes on workstation NA Yes (1) setup virtual env, then make.bat, make, (2) Potentially provide toolchain as a Slicer extension ??
Support update pushed on GitHub No Yes Yes (through sync mechanism, conflict could happen)
Possibility to review changes Only afterward Yes (with Pull Request) Yes (with Change Request)
Manage documentation version Difficult Easy ??
Allow reader to annotate No

(or through https://hypothes.is/)

No

(or through https://hypothes.is/)

Yes - Built in
Allow reader to comment on page Yes

Talk page (Not used in practice)

No Yes
Formatting tables Yes (using www.tablesgenerator.com Yes (using www.tablesgenerator.com Yes (using builtin table editor)
Support table sorting Easy (builtin css class + js) Yes (To be added to js and css) Yes (To be added to js and css)
Automatic TOC generation Yes Yes Yes
Cross-referencing section Yes Yes ??
Link to existing documentation (Qt, VTK, ...) Using direct link Using direct link (or intersphinx) Using direct link
Sharing link to page section Yes

After clicking on TOC entry at the top

Yes

Anchor available near section title

Yes

After clicking on TOC entry on the right

Cross-platform generation toolchain Not available Yes ??
Indexing by search engine Difficult, involve tweaking page headers, updating robots.txt, ... ?? ??
Analytics Possible with Google analytics (with Extension:Google_Analytics_Integration Builtin support for Google analytics Built-in (but no per page stats)
Extensible using plugin Server side extension Toolchain plugins Toolchain plugins
Local testing of plugin NA update "conf.py" and python import ???
Reference Github user Direct link Direct link Direct link
Reference Github issue Direct link Using sphinx_issues extension Direct link
Reference Github commit Direct link Direct link Direct link
Code Syntax Highlight Yes (with Extension:SyntaxHighlight) Yes Yes
Maintaining embedded code snippet Code is copied - Hard to maintain (automatic publication could be done using API) Easy - By including tested source file using include directive ??
Document python API No (or very difficult) Easy - Using sphinx-apidoc and python domain directive ??
Document python wrapped VTK-based classes No (or very difficult) Moderate

(using sphinx-apidoc, downloading latest version)

??
Document pythonQt wrapped Qt -based classes No (or very difficult) Hard

(running sphinx api-doc from within Slicer) - **Need to experiment**

??
Document CMake API No (or very difficult) Easy - using sphinx cmake extension ??
Document Cpp API generated from Doxygen No (or very difficult) To be tested - Using doxygen + breathe sphinx extension ??

Proposing changes

GitBook

  • 1. Click Edit link

  • 2. Fork

  • 3. Edit and propose changes

ReadTheDocs

  • 1. Click "Edit the source" link

  • 2. Click Edit link

  • 3. Edit and propose changes

Uploading Images

ReadTheDocs / GitHub

  • 1. Edit source, browse to images folder and click upload files

  • 2. Drag and drop image(s)

  • 3. Type commit message, select create a new branch and click "Propose Changes"

  • 4. Type PR name and click "Create Pull Request"

  • 5. Browse to the branch created on your fork and select the file to edit

  • 6. Edit file and reference image uploaded in previous commit

Diff'ing Changes

ReadTheDocs / GitHub

  • Visual diff for markdown and reStructuredText. Note that special directive are not rendered

Gitbook

  • Visual diff for markdown.


Documenting Slicer APIs

There are 4 types of object to document:

  • pure python classes
  • python wrapped VTK classes
  • pythonqt wrapped Qt classes
  • c++ classes

ReadTheDocs / GitHub

pure python classes

List of automodules directives is generated using `sphinx-apidoc`. List can be updated re-running `sphinx-apidoc` or by manually adding entries.

An entry look like: 

slicer.cli module
-----------------

.. automodule:: slicer.cli
    :members:
    :undoc-members:
    :show-inheritance:


python wrapped VTK classes

Documentation for these classes can also automatically be generated using sphinx-apidoc and automodule directive.

Locally, I experimented by updating LD_LIBRARY_PATH and PYTHONPATH with Slicer paths but made sure to exclude OpenSSL and Slicer built-in python.

That allow to generate the documentation for vtkITK, teem, .... See below for an example:

Rtd-vtk-python-wrapped.png

pythonqt wrapped Qt classes

To be done

c++ classes

Doxygen is currently doing a good job extracting and generating documentation.

Current platform: Issues and features

slicer.org

  • Check.svg 2015-11-22 1967: Improve "slicer.org" page - Easier access to build / download / contribute

download.slicer.org

  • 1966: Add disclaimer associated with 32bit on download.slicer.org
  • Check.svg 2015-11-22 1991: Cosmetics for the slicer download page

Mediawiki: wiki.slicer.org

  1. Issue reports and feature requests can be listed using this link:
    http://tinyurl.com/zzssdfb

Infrastructure

  • 2971: Install MetaTags extension
    • Would be great to try it. Note that dependent extension StubManager is not maintained anymore
  • 1543: Install CategoryTree extension
  • 2190: Fix graphviz installation on Slicer wiki
  • 2170: Install extension SyntaxHighlight_GeSHi on Slicer wiki
  • Check.svg 2015-11-22 2272: Simplfy the first screen of the Slicer documentation page
  • 2968: Slicer wiki - Enable short url => easier configuration of robots.txt
  • Account
    • 4216: Wiki: Notify Slicer core developers
  • Analytics
    • 4215: Notify Slicer core developers when an account is created
  • Improved UI
    • 4214: Wiki: Add support for vectorial fonts
Google Calendar
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Labs/DocumentationImprovments&oldid=50562"