Spinalcordtoolbox: Start Sphinx documentation

[jcohenadad]

[zougloub]

https://spinalcordtoolbox.readthedocs.io or https://spinalcordtoolbox.github.io ?

[perone]

I would go with ReadTheDocs, they do an automatic build of the docs for multiple repo tags, etc.

[zougloub]

There's a tiny possibility that the build environment of readthedocs is too limited for building the docs, though.

[zougloub]

Github Pages can do the trick though, for now I've manually built docs at https://zougloub.github.io/sct_docs ; this is from a repo containing Sphinx HTML outputs.
If we're really bored of committing by hand, the repo could contain a Travis script to generate the docs and publish the Github page.

[jcohenadad]

Fantastic contribution @zougloub! I'm not a big fan of the font (i would favor something like this) but that's a minor detail. I guess the next big step is to get the meat inside, and i should probably be the one to get my hands dirty

[zougloub]

@perone are you OK with Github Pages? and with a separate repo for building/storing docs?
@abtahizadeh do you have an opinion?
@jcohenadad changed theme to the Read The Docs one.

[perone]

I think it's ok to have a separate repo, you can even get a cheap DNS later like spinalcordtoolbox.org or something like that that will point to the repo. My only concern is the manual rendering of docs every time they get an update, we had this for axondeepseg which is quite small and it was terrible, but after we moved to readthedocs, things got much better and easier, so if we have an automated way of rendering docs (travis, whatever) I would say it's ok.

But why don't we use the gh-page of the spinalcordtoolbox to host the docs ? I didn't get the reason to host in another repository.

[alexfoias]

We already have a DNS on rebrandly called neuropoly.pub

[zougloub]

Travis can push to Github Pages (I'll do it later).

I started trying to use gh-pages on the spinalcordtoolbox repo, it can be used also, but I'd lean towards using a separate repo:

• Avoids having different stuff in a single repo (it's "cleaner");
• Pollution that would happen on git fetch;
• We may want to have docs for each SCT release (if you read master's docs and they refer to stuff that doesn't exist in your release...), which means that the repo would grow a little;
• Separate Travis without having a crazy build matrix or wasting time on making docs.

[perone]

I see, but all these issues seem to be what ReadTheDocs solve right ?

• You have a separate hosting, so no gh-pages;
• No pollution on git fetch because the rendered docs aren't hosted on the repo;
• ReadTheDocs naturally have versioning implemented for master/dev/releases;
• No need to use Travis to build and push;

So I wonder if it's worth building all those features ourselves if we have for free from ReadTheDocs.

[zougloub]

I couldn't get RTD to build the documentation (it means having an SCT installation).

[perone]

I saw it, but what is the problem that you're facing with RTD ?

[zougloub]

Installing SCT (Conda and all that stuff), then working in that environment to be able to get API auto-docs.

[abtahizadeh]

I'm always fan of github.io 🥇
May I ask what neuropoly.pub is intended to use for?

[jcohenadad]

@abtahizadeh please disregard Alex's message about neuropoly.pub, this is unrelated to SCT

[abtahizadeh]

https://github.com/fmtlib/fmt/issues/128
:-D

[jcohenadad]

thank you @abtahizadeh for reviving the debate. I would also tend to go for github.io page (hoping it won't turn into github.microsoft issues in the near future...). Others, any thoughts?

[zougloub]

At this point I'd just like to push the docs. I'd prefer to curate the generated docs in their own repo, vs. bloating this one even more (that repo will grow as we keep the docs for past releases).

[jcohenadad]

Another argument in favour of github.io is the absence of ads (when using the free version of RTD).

[jcohenadad]

@Drulex @kousu do you have any opinion on the RTD vs. Github pages debate?

[Drulex]

@Drulex @kousu do you have any opinion on the RTD vs. Github pages debate?

No prior experience or preference. If the features are similar I would go with the simpler solution to deploy.

[jcohenadad]

github is simpler (all integrated) and faster, but RTD makes it easy to build specific branch (which is good if we want to have a preview before merging to master)

[Drulex]

We could also do both (if not too much work) and see!

[jcohenadad]

Fixed in #2781