Project page hosting on GitHub?

(Andras Lasso) #1

I’ve ported a couple of intro pages and the current project week page from Slicer wiki to GitHub to show how we could use GitHub for project week page hosting:

Published website (using default blank theme): https://na-mic.github.io/ProjectWeek/

Example project page: https://na-mic.github.io/ProjectWeek/PW27_2018_Boston/Projects/SlicerVR/

Link for editing/uploading pages: https://github.com/NA-MIC/ProjectWeek

Editable project template: https://github.com/NA-MIC/ProjectWeek/blob/master/PW27_2018_Boston/Projects/Template/README.md

Main advantages of GitHub:

  • Full offline access. Entire wiki can be downloaded and viewed/edited on a laptop, without network access.
  • Developer familiarity. All developers have GitHub account and familiar with how to upload and edit files.
  • Uses Markdown, a very commonly used markup style (used for in the Slicer forum, GitHub, Slack, etc). MediaWiki markup is only used on MediaWiki sites.

Should we start using GitHub for hosting projects pages for this project week?

@Tina_Kapur @jcfr @pieper @ihnorton @cpinter @ungi

EDITED: Changed project name from ProjectWeek into SlicerProjectWeeks
EDITED #2: Changed back to ProjectWeek to be inclusive and not focused on a specific platform.
EDITED #3: Changed 27 to PW27_2018_Boston

2 Likes
(Andrey Fedorov) #2

I agree there are many advantages moving away from the wiki. Another one to add to the list is that the process becomes much easier for new users to get an account and contribute content. It happened several times in my memory when users requested wiki accounts, but their request was misplaced, or took too long to approve.

I am struggling to think of disadvantages moving away from the wiki. Perhaps it is the ranking of the existing pages, but I would think that should be resolved with cross-linking.

However, I do not think web page is the right format. I would recommend GitBook. In addition to all of the advantages listed above:

  • it supports hierarchical organization of the content
  • content can be edited in a WYSIWYG editor, or directly in Markdown
  • content can be contributed using either GitHub pull request, or direct edit of the content

See example here: https://qiicr.gitbooks.io/dcmqi-guide/content/. GitBook is also working on a new release, which has (in my view) further streamlined presentation (I have not spent a lot of time investigating the new one, just learned about it this week), see example of the same content on the new platform here: https://qiicr.gitbook.io/dcmqi-guide/.

(Andrey Fedorov) #3

I could put together an example of how this would look like on GitBook a bit later, if interested, so we can compare side by side…

(Andras Lasso) #4

GitBook is just another html generator/hosting with some nice additional tools and it’s own Markdown flavor. We don’t need to decide on which generator(s) we will use, as we’ll host and edit Markdown files on GitHub anyway.

Last time we checked GitBook was not open to provide their service freely to a large number of users. Has anything changed?

In addition to GitBook, we may consider GitHub pages with various templates, Sphinx/ReadTheDocs, Reveal.js, etc. If we keep things simple then we can probably remain compatible with multiple generators.

(Andras Lasso) #5

You can probably generate a gitbook from the current repository (maybe fork it so that you can experiment with what additional template and other files you have to add).

(Jean Christophe Fillion Robin) #6

Well done :slight_smile:

I like it.

Any objection in renaming the project to “slicer-project-week” or “SlicerProjectWeek” ?

becomes much easier for new users to get an account and contribute content. It happened several times in my
memory when users requested wiki accounts, but their request was misplaced, or took too long to approve.

For the wiki, I think the idea was to avoid systematically granting access to everyone and explicitly authorize individual. We could change that and it will greatly streamline contribution. I start an other topic to discuss this.

The advantage of Github is that anyone can submit a PR without having anyone explicitly granting access before hand. This will indeed streamline the process.

(Andras Lasso) #7

I actually wanted to rename it to SlicerProjectWeeks but did not have the required access level. I think SlicerProjectWeeks is better than SlicerProjectWeek, as most likely we would host multiple project weeks in the same repository.

(Andras Lasso) #8

We’ll have to see what works well in practice but we could grant write access to each person who submits a pull request with a meaningful project page. With protected branches it is quite safe to grant people write access, as it prevents accidentally overwriting the history. But I would expect that most people would directly edit the pages on the web GUI.

1 Like
(Csaba Pinter) #9

In this page https://help.github.com/articles/about-protected-branches I read “Can’t be edited or have files uploaded to it from the web”. If it is still like this, then making it a protected branch would make it much harder to edit pages as every change would require a PR or git commit.

(Andras Lasso) #10

I’ve just tried and you can commit directly into a protected branch. I think protected branches got more sophisticated during the past years - you can set it up to only disable force push and delete of the branch.

(Andrey Fedorov) #11

Pure Markdown will not be sufficient, as we will need to adjust image sizes, insert videos etc. So some flavor of Markdown will be necessary. I don’t think flavors will migrate seamlessly across the various content management services you mentioned.

What do you mean? If you mean large number of collaborators on a single book, then yes - that is constrained. We can apply for free next tier subscription, and that will increase the number of collaborators on a single book to 10. We did this for QIICR.

However, it that is not really critical, since GitBook content can be synchronized with a GitHub repo, which can follow conventional GitHub contribution workflow, and the GitBook automatically updated to track master or another selected branch. I think it should also be possible for other contributors to fork the GitHub repo, make a GitBook from that fork, edit content using visual editor on a specific branch, and then make a pull request back upstream.

(Jean Christophe Fillion Robin) #12

Repository renamed to SlicerProjectWeeks . See https://na-mic.github.io/SlicerProjectWeeks/

EDITED: Changed project name changed back to ProjectWeek so pages are available at https://na-mic.github.io/ProjectWeek/

Strange. You have “Owner” role within the NA-MIC GitHub organization.

:+1:

For youtube video, the preview picture could be added. See here

For adjusting image size, using <img width="250px" src="https://url/to/image.png"> should work

(Steve Pieper) #13

I suspect there will be a learning curve for the community no matter which method we pick. Hosting directly from github markdown pages seems the most “standard” and for that reason I think that people will derive the most educational benefit from getting familiar with the github process and github markdown, even if we have to live with some limitations (which so far seem fairly minor for our purposes).

1 Like
(Andras Lasso) #14

I agree. We can start with plain markdown syntax, it’s simple and compatible with everything. Once we gathered some initial experience, we can make much better informed decisions about how to improve things.

Has anybody talked to @Tina_Kapur? If she is OK with this, too, then we should announce that project pages should be created in this GitHub repository (and update the wiki page so that it points to the GitHub page).

(Jean Christophe Fillion Robin) #15

Nitpick:

Instead of 27 as the name of the directory, should we follow a convention like <Number>_<YYYY-MM>_<COUNTRY>_<CITY>

For example:

25_2017-06_Italy_Calabria
27_2018-01_USA_Boston
1 Like
(Isaiah Norton) #16

I think these are too long and annoying to type during the week – especially on mobile. So could we please at least set up projectweek.slicer.org or even pw.slicer.org as a redirect?

(I’m not sure why would these semantic URLs be useful? no one is going to remember how to type that, and google doesn’t care anyway :slight_smile: )

1 Like
(Steve Pieper) #17

The value of the semantic URL to me would be when you send or embed a link it would be easier to know in advance what you are linking to.

+1 to the idea of pw.slicer.org as a redirect.

1 Like
(Andras Lasso) #18

In same cases more verbose, in other situations simpler, more predictable names are better.

Probably 27 is not trivial to interpret, while 27_2018-01_USA_Boston is a bit too long to type. What about these?

  • PW27
  • PW27_2018_Boston
  • PW27_2018_Jan_Boston
(Csaba Pinter) #19

I support finding some middle ground. My vote goes to PW27_2018_Boston, I think it’s not hard to remember even if you need to type it, and you’ll know when and where that project week was.

1 Like
(Andrey Fedorov) #20

I would definitely suggest pw.na-mic.org. Branding project week with a specific platform can create various issues now and especially in the future. We should be inclusive, and think about possible issues down the road. I also think that this kind of decision should involve Ron. Monitoring updates from discourse can be cumbersome, and I suggest we should email Ron directly to seek his input.