Difference between revisions of "Documentation/Labs/DocumentationImprovments"

From Slicer Wiki
Jump to: navigation, search
Line 100: Line 100:
  
 
=== Summary ===
 
=== Summary ===
 +
 +
Legend:
  
 
{| class="wikitable"
 
{| class="wikitable"
 +
! Very Easy
 +
| class="veryeasy"    | builtin feature, minimal setup
 +
| <code>class="veryeasy"</code>
 +
|-
 
! Easy
 
! Easy
−
| style="background-color:MediumSeaGreen;"| builtin feature, minimal setup
+
| class="easy"| simple install, simple script or cron job
−
| <code>style="background-color:MediumSeaGreen;"</code>
+
| <code>class="easy"</code>
 
|-
 
|-
 
! Moderate
 
! Moderate
−
| style="background-color:lightgreen;"| simple install, simple script or cron job
+
| class="difficult"| involved development, advanced setup, not streamlined
−
| <code>style="background-color:lightgreen;"</code>
+
| <code>class="difficult"</code>
 
|-
 
|-
 
! Difficult
 
! Difficult
−
| style="background-color:orange;"| involved development, advanced setup, not streamlined
+
| class="difficult"| Not available, doesn't make sense, very involved hackery
−
| <code>style="background-color:orange;"</code>
+
| <code>class="difficult"</code>
−
|-
 
−
! Not available
 
−
| style="background-color:LightCoral;"| doesn't make sens
 
−
| <code>style="background-color:lightCoral;"</code>
 
 
|}
 
|}
  
 +
List of features for each platforms:
  
−
{| class="wikitable"
+
{| class="wikitable feature_compare_table"
 
!  
 
!  
 
! MediaWiki
 
! MediaWiki
Line 127: Line 130:
 
|-
 
|-
 
| Sign-up for contributor account
 
| Sign-up for contributor account
−
| style="background-color:orange;"       | Dedicated Account
+
| class="difficult" | Dedicated Account
−
| style="background-color:MediumSeaGreen;"| Github Account
+
| class="veryeasy" | Github Account
−
| style="background-color:MediumSeaGreen;"| Github Account
+
| class="veryeasy" | Github Account
 
|-
 
|-
 
| From Web: Create a new page
 
| From Web: Create a new page
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
−
| style="background-color:lightgreen;"   | Moderate (step 1, create file, step 2, update index)
+
| class="easy"     | Moderate (step 1, create file, step 2, update index)
−
| style="background-color:MediumSeaGreen;"| Easy (using "Add Article")
+
| class="veryeasy" | Easy (using "Add Article")
 
|-
 
|-
 
| From Web: Edit exiting page
 
| From Web: Edit exiting page
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
 
|-
 
|-
 
| From Web: Edit exiting page uploading images
 
| From Web: Edit exiting page uploading images
−
| style="background-color:lightgreen;"   | Easy (Click upload link, select image, confirm)
+
| class="easy"     | Easy (Click upload link, select image, confirm)
−
| style="background-color:LightCoral;"   | Very difficult
+
| class="moderate" | Not straighforward, a lot of steps
−
| style="background-color:MediumSeaGreen;"| Easy (Click upload, Drag'n drop, Confirm)
+
| class="veryeasy" | Easy (Click upload, Drag'n drop, Confirm)
 
|-
 
|-
 
| From Web: Preview local changes
 
| From Web: Preview local changes
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
 
|-
 
|-
 
| From Web: Preview changes for complete website
 
| From Web: Preview changes for complete website
−
| style="background-color:LightCoral;"   | NA
+
| class="difficult" | NA
−
| style="background-color:MediumSeaGreen;"| No (or difficult would need to deploy topic/PR in dedicated github page)
+
| class="veryeasy" | No (or difficult would need to deploy topic/PR in dedicated github page)
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
|-
 
|-
 
| Changes available in Git
 
| Changes available in Git
−
| style="background-color:LightCoral;"   | No (or very difficult to setup)
+
| class="difficult" | No (or very difficult to setup)
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:lightgreen;"   | Yes (through sync mechanism, conflict could happen)
+
| class="easy"     | Yes (through sync mechanism, conflict could happen)
 
|-
 
|-
 
| Preview changes on workstation
 
| Preview changes on workstation
−
| style="background-color:LightCoral;"   | NA
+
| class="difficult" | NA
−
| style="background-color:lightgreen;"   | Yes (1) setup virtual env, then make.bat, make, (2) Potentially provide toolchain as a Slicer extension
+
| class="easy"     | Yes (1) setup virtual env, then make.bat, make, (2) Potentially provide toolchain as a Slicer extension
 
| ??
 
| ??
 
|-
 
|-
 
| Support update pushed on GitHub
 
| Support update pushed on GitHub
−
| style="background-color:LightCoral;    "| No
+
| class="difficult" | No
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:lightgreen;"   | Yes (through sync mechanism, conflict could happen)
+
| class="easy"     | Yes (through sync mechanism, conflict could happen)
 
|-
 
|-
 
| Possibility to review changes
 
| Possibility to review changes
−
| style="background-color:lightgreen;"   | Only afterward
+
| class="easy"     | Only afterward
−
| style="background-color:MediumSeaGreen;"| Yes (with Pull Request)
+
| class="veryeasy" | Yes (with Pull Request)
−
| style="background-color:MediumSeaGreen;"| Yes (with Change Request)
+
| class="veryeasy" | Yes (with Change Request)
 
|-
 
|-
 
| Manage documentation version
 
| Manage documentation version
−
| style="background-color:LightCoral;"   | Difficult
+
| class="difficult" | Difficult
−
| style="background-color:MediumSeaGreen;"| Easy
+
| class="veryeasy" | Easy
 
| ??
 
| ??
 
|-
 
|-
 
| Allow reader to annotate
 
| Allow reader to annotate
−
| style="background-color:LightCoral;"   | No
+
| class="moderate" | No
 
(or through https://hypothes.is/)
 
(or through https://hypothes.is/)
−
| style="background-color:LightCoral;"   | No  
+
| class="moderate" | No  
 
(or through https://hypothes.is/)
 
(or through https://hypothes.is/)
−
| style="background-color:MediumSeaGreen;"| Yes - Built in
+
| class="veryeasy" | Yes - Built in
 
|-
 
|-
 
| Allow reader to comment on page
 
| Allow reader to comment on page
−
| style="background-color:lightgreen;"   | Yes  
+
| class="easy"     | Yes  
 
Talk page (Not used in practice)
 
Talk page (Not used in practice)
−
| style="background-color:LightCoral;"   | No
+
| class="difficult" | No
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
|-
 
|-
 
| Formatting tables
 
| Formatting tables
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
|-
 
|-
 
| Support table sorting
 
| Support table sorting
−
| style="background-color:MediumSeaGreen;"| Easy (builtin css class + js)
+
| class="veryeasy" | Easy (builtin css class + js)
−
| Yes (To be added to js and css)
+
| class="moderate"  | Yes (To be added to js and css)
−
| Yes (To be added to js and css)
+
| class="moderate"  | Yes (To be added to js and css)
 
|-
 
|-
 
| Automatic TOC generation
 
| Automatic TOC generation
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
|-
 
|-
 
| Cross-referencing section
 
| Cross-referencing section
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
| ??
 
| ??
 
|-
 
|-
 
| Link to existing documentation (Qt, VTK, ...)
 
| Link to existing documentation (Qt, VTK, ...)
−
| style="background-color:MediumSeaGreen;"|Using direct link
+
| class="veryeasy" | Using direct link
−
| style="background-color:MediumSeaGreen;"|Using direct link (or intersphinx)
+
| class="veryeasy" | Using direct link (or intersphinx)
−
| style="background-color:MediumSeaGreen;"|Using direct link
+
| class="veryeasy" | Using direct link
 
|-
 
|-
 
| Sharing link to page section
 
| Sharing link to page section
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
After clicking on TOC entry at the top
 
After clicking on TOC entry at the top
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
Anchor available near section title
 
Anchor available near section title
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
After clicking on TOC entry on  the right
 
After clicking on TOC entry on  the right
 
|-
 
|-
 
| Cross-platform generation toolchain
 
| Cross-platform generation toolchain
−
| style="background-color:LightCoral;"   | Not available
+
| class="difficult" | Not available
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
| ??
 
| ??
 
|-
 
|-
 
| Indexing by search engine
 
| Indexing by search engine
−
| style="background-color:LightCoral;"   | Very Difficult
+
| class="difficult" | Difficult, involve tweaking page headers, updating robots.txt, ...
 
| ??
 
| ??
 
| ??
 
| ??
 
|-
 
|-
 
| Analytics
 
| Analytics
−
| style="background-color:orange;"       | Possible with Google analytics (with [https://www.mediawiki.org/wiki/Extension:Google_Analytics_Integration Extension:Google_Analytics_Integration]
+
| class="moderate" | Possible with Google analytics (with [https://www.mediawiki.org/wiki/Extension:Google_Analytics_Integration Extension:Google_Analytics_Integration]
−
| style="background-color:MediumSeaGreen;"| Builtin support for Google analytics
+
| class="veryeasy" | Builtin support for Google analytics
−
| style="background-color:lightgreen;"   | Built-in (but no per page stats)
+
| class="easy"     | Built-in (but no per page stats)
 
|-
 
|-
 
| Extensible using plugin
 
| Extensible using plugin
−
| style="background-color:orange;"       | Server side extension
+
| class="difficult" | Server side extension
−
| style="background-color:lightgreen;"   | Toolchain plugins
+
| class="moderate" | Toolchain plugins
−
| style="background-color:lightgreen;"   | Toolchain plugins
+
| class="moderate" | Toolchain plugins
 +
|-
 +
| Local testing of custom plugin
 +
| class="difficult" | NA
 +
| class="easy"      | update "conf.py" and python import
 +
| ???
 
|-
 
|-
 
| Reference Github user
 
| Reference Github user
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
 
|-
 
|-
 
| Reference Github issue
 
| Reference Github issue
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
−
| style="background-color:lightgreen;"   | Using sphinx_issues extension
+
| class="easy"     | Using sphinx_issues extension
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
 
|-
 
|-
 
| Reference Github commit
 
| Reference Github commit
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
−
| style="background-color:lightgreen;"   | Direct link
+
| class="easy"     | Direct link
 
|-
 
|-
 
| Code Syntax Highlight
 
| Code Syntax Highlight
−
| style="background-color:lightgreen;"   | Yes (with [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight Extension:SyntaxHighlight])
+
| class="easy"     | Yes (with [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight Extension:SyntaxHighlight])
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
−
| style="background-color:MediumSeaGreen;"| Yes
+
| class="veryeasy" | Yes
 
|-
 
|-
 
| Maintaining embedded code snippet
 
| Maintaining embedded code snippet
−
| style="background-color:orange;"       | Code is copied - Hard to maintain (automatic publication could be done using API)
+
| class="difficult" | Code is copied - Hard to maintain (automatic publication could be done using API)
−
| style="background-color:MediumSeaGreen;"| Easy - By including tested source file using [http://www.sphinx-doc.org/en/stable/markup/code.html#includes include] directive
+
| 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
 
| Document python API
−
| style="background-color:lightCoral;"   | No (or very difficult)
+
| class="difficult" | No (or very difficult)
−
| style="background-color:lightgreen;"   | Easy - Using sphinx-apidoc and python domain directive
+
| class="easy"     | Easy - Using sphinx-apidoc and python domain directive
 
| ??
 
| ??
 
|-
 
|-
 
| Document python wrapped VTK-based classes
 
| Document python wrapped VTK-based classes
−
| style="background-color:LightCoral;"   | No (or very difficult)
+
| class="difficult" | No (or very difficult)
−
| style="background-color:lightgreen;"   | Moderate
+
| class="easy"     | Moderate
 
(using sphinx-apidoc, downloading latest version)
 
(using sphinx-apidoc, downloading latest version)
 
| ??
 
| ??
 
|-
 
|-
 
| Document pythonQt wrapped Qt -based classes
 
| Document pythonQt wrapped Qt -based classes
−
| style="background-color:LightCoral;"   | No (or very difficult)
+
| class="difficult" | No (or very difficult)
−
| style="background-color:Orange;"       | Hard
+
| class="difficult" | Hard
 
(running sphinx api-doc from within Slicer) - **Need to experiment**
 
(running sphinx api-doc from within Slicer) - **Need to experiment**
 
| ??
 
| ??
 
|-
 
|-
 
| Document CMake API
 
| Document CMake API
−
| style="background-color:LightCoral;"   | No (or very difficult)
+
| class="difficult" | No (or very difficult)
−
| style="background-color:lightgreen;"   | Easy - using sphinx cmake extension
+
| class="easy"     | Easy - using sphinx cmake extension
 
| ??
 
| ??
 
|-
 
|-
 
| Document Cpp API generated from Doxygen
 
| Document Cpp API generated from Doxygen
−
| style="background-color:LightCoral;"   | No (or very difficult)
+
| class="difficult" | No (or very difficult)
−
| style="background-color:orange;"      | Moderate - Using doxygen + breathe sphinx extension
+
| To be tested - Using doxygen + breathe sphinx extension
 
| ??
 
| ??
 
|}
 
|}

Revision as of 22:11, 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="difficult"
Difficult Not available, doesn't make sense, very involved hackery class="difficult"

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 Yes Yes
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 custom 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.

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=50530"