Difference between revisions of "Documentation/Labs/DocumentationImprovments"
From Slicer Wiki
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 | ||
− | | | + | | class="easy"| simple install, simple script or cron job |
− | | <code> | + | | <code>class="easy"</code> |
|- | |- | ||
! Moderate | ! Moderate | ||
− | | | + | | class="difficult"| involved development, advanced setup, not streamlined |
− | | <code> | + | | <code>class="difficult"</code> |
|- | |- | ||
! Difficult | ! Difficult | ||
− | | | + | | class="difficult"| Not available, doesn't make sense, very involved hackery |
− | + | | <code>class="difficult"</code> | |
− | |||
− | |||
− | |||
− | | <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 | ||
− | | | + | | class="difficult" | Dedicated Account |
− | | | + | | class="veryeasy" | Github Account |
− | | | + | | class="veryeasy" | Github Account |
|- | |- | ||
| From Web: Create a new page | | 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 | | From Web: Edit exiting page | ||
− | | | + | | class="veryeasy" | Easy |
− | | | + | | class="veryeasy" | Easy |
− | | | + | | class="veryeasy" | Easy |
|- | |- | ||
| From Web: Edit exiting page uploading images | | 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 | | From Web: Preview local changes | ||
− | | | + | | class="veryeasy" | Easy |
− | | | + | | class="veryeasy" | Easy |
− | | | + | | class="veryeasy" | Easy |
|- | |- | ||
| From Web: Preview changes for complete website | | 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 | | 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 | | 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 | | Support update pushed on GitHub | ||
− | | | + | | class="difficult" | No |
− | | | + | | class="veryeasy" | Yes |
− | | | + | | class="easy" | Yes (through sync mechanism, conflict could happen) |
|- | |- | ||
| Possibility to review changes | | Possibility to review changes | ||
− | | | + | | class="easy" | Only afterward |
− | | | + | | class="veryeasy" | Yes (with Pull Request) |
− | | | + | | class="veryeasy" | Yes (with Change Request) |
|- | |- | ||
| Manage documentation version | | Manage documentation version | ||
− | | | + | | class="difficult" | Difficult |
− | | | + | | class="veryeasy" | Easy |
| ?? | | ?? | ||
|- | |- | ||
| Allow reader to annotate | | Allow reader to annotate | ||
− | | | + | | class="moderate" | No |
(or through https://hypothes.is/) | (or through https://hypothes.is/) | ||
− | | | + | | class="moderate" | No |
(or through https://hypothes.is/) | (or through https://hypothes.is/) | ||
− | | | + | | class="veryeasy" | Yes - Built in |
|- | |- | ||
| Allow reader to comment on page | | Allow reader to comment on page | ||
− | | | + | | class="easy" | Yes |
Talk page (Not used in practice) | Talk page (Not used in practice) | ||
− | | | + | | class="difficult" | No |
− | | | + | | class="veryeasy" | Yes |
|- | |- | ||
| Formatting tables | | Formatting tables | ||
− | | | + | | class="veryeasy" | Yes |
− | | | + | | class="veryeasy" | Yes |
− | | | + | | class="veryeasy" | Yes |
|- | |- | ||
| Support table sorting | | Support table sorting | ||
− | | | + | | 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 | ||
− | | | + | | class="veryeasy" | Yes |
− | | | + | | class="veryeasy" | Yes |
− | | | + | | class="veryeasy" | Yes |
|- | |- | ||
| Cross-referencing section | | Cross-referencing section | ||
− | | | + | | class="veryeasy" | Yes |
− | | | + | | class="veryeasy" | Yes |
| ?? | | ?? | ||
|- | |- | ||
| Link to existing documentation (Qt, VTK, ...) | | 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 | | Sharing link to page section | ||
− | | | + | | class="veryeasy" | Yes |
After clicking on TOC entry at the top | After clicking on TOC entry at the top | ||
− | | | + | | class="veryeasy" | Yes |
Anchor available near section title | Anchor available near section title | ||
− | | | + | | 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 | ||
− | | | + | | class="difficult" | Not available |
− | | | + | | class="veryeasy" | Yes |
| ?? | | ?? | ||
|- | |- | ||
| Indexing by search engine | | Indexing by search engine | ||
− | | | + | | class="difficult" | Difficult, involve tweaking page headers, updating robots.txt, ... |
| ?? | | ?? | ||
| ?? | | ?? | ||
|- | |- | ||
| Analytics | | 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 | | Extensible using plugin | ||
− | | | + | | class="difficult" | Server side extension |
− | | | + | | class="moderate" | 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 | ||
− | | | + | | class="easy" | Direct link |
− | | | + | | class="easy" | Direct link |
− | | | + | | class="easy" | Direct link |
|- | |- | ||
| Reference Github issue | | Reference Github issue | ||
− | | | + | | class="easy" | Direct link |
− | | | + | | class="easy" | Using sphinx_issues extension |
− | | | + | | class="easy" | Direct link |
|- | |- | ||
| Reference Github commit | | Reference Github commit | ||
− | | | + | | class="easy" | Direct link |
− | | | + | | class="easy" | Direct link |
− | | | + | | class="easy" | Direct link |
|- | |- | ||
| Code Syntax Highlight | | 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 | | 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 | | 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 | | Document python wrapped VTK-based classes | ||
− | | | + | | class="difficult" | No (or very difficult) |
− | | | + | | 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 | ||
− | | | + | | class="difficult" | No (or very difficult) |
− | | | + | | 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 | ||
− | | | + | | class="difficult" | No (or very difficult) |
− | | | + | | class="easy" | Easy - using sphinx cmake extension |
| ?? | | ?? | ||
|- | |- | ||
| Document Cpp API generated from Doxygen | | Document Cpp API generated from Doxygen | ||
− | | | + | | class="difficult" | No (or very difficult) |
− | | | + | | To be tested - Using doxygen + breathe sphinx extension |
| ?? | | ?? | ||
|} | |} |
Revision as of 22:11, 22 March 2017
Home < Documentation < Labs < DocumentationImprovmentsThis page keeps track of possible improvement related to the Slicer documentation infrastructure.
Contents
Experiments
User manual with GitBook
- 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/
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.
- New users 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 ?
- Nice example of a front page for a project: https://robomongo.org/
Improved FAQ
- Spreadsheet about mailing list questions: File:UsersMailingListSlicer4.5.xlsx (between 2015.11. and 2016.07., by Hillary Lia)
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:
- 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:
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
ReadTheDocs
Uploading Images
ReadTheDocs / GitHub
Diff'ing Changes
ReadTheDocs / GitHub
Gitbook
Current platform: Issues and features
slicer.org
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.org2015-11-22
1991: Cosmetics for the slicer download page
Mediawiki: wiki.slicer.org
- 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
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
- Variables extension:
- Analytics
- 4215: Notify Slicer core developers when an account is created
- Improved UI
- 4214: Wiki: Add support for vectorial fonts
- YouTube extension:
Google Calendar
- Google Calendar
https://www.mediawiki.org/wiki/Extension:GoogleCalendarThis 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