Difference between revisions of "Documentation/Labs/DocumentationImprovments"

From Slicer Wiki
Jump to: navigation, search
Line 98: Line 98:
  
 
== New Platform: Comparison ==
 
== New Platform: Comparison ==
 +
 +
=== Summary ===
 +
 +
{| class="wikitable"
 +
!
 +
! 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 (Few steps)
 +
| Very difficult
 +
| Easy (Drag'n drop)
 +
|-
 +
| 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)
 +
|-
 +
| Preview changes locally
 +
| 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)
 +
|-
 +
| 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
 +
| Very Difficult
 +
| ??
 +
| ??
 +
|-
 +
| Analytics
 +
| Possible with Google analytics
 +
| Builtin support for Google analytics
 +
| Built-in (but no per page stats)
 +
|-
 +
| Extensible using plugin
 +
| Server side extension
 +
| Toolchain plugins
 +
| Toolchain plugins
 +
|-
 +
| 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
 +
| Yes
 +
| Yes
 +
|-
 +
| Embed code snippet
 +
| By copying - Hard to maintain
 +
| Easy - By using
 +
| ??
 +
|-
 +
| 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
 +
| No (or very difficult)
 +
| Easy - Using cpp domain directive
 +
| ??
 +
|-
 +
| Document Cpp API generate from Doxygen
 +
| No (or very difficult)
 +
| Moderate - Using doxygen + breathe sphinx extension
 +
| ??
 +
|}
  
 
=== Proposing changes ===
 
=== Proposing changes ===

Revision as of 20:09, 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

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 (Few steps) Very difficult Easy (Drag'n drop)
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)
Preview changes locally 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)
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 Very Difficult ?? ??
Analytics Possible with Google analytics Builtin support for Google analytics Built-in (but no per page stats)
Extensible using plugin Server side extension Toolchain plugins Toolchain plugins
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 Yes Yes
Embed code snippet By copying - Hard to maintain Easy - By using ??
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 No (or very difficult) Easy - Using cpp domain directive ??
Document Cpp API generate from Doxygen No (or very difficult) Moderate - 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=50484"