[DOC] Use sphinx for documentation about bids-matlab HOT 6 CLOSED

The Sphinx extension seems great but I wonder if that's a reason enough to use Sphinx. How do you envisage the documentation to look like? Here, I find that tutorials can be more suited to convey how to use bids-matlab. The MATLAB Sphinx example looks nice but targeting developers more than users.
Or perhaps it's just because I find Material for MkDocs prettier 😄

from bids-matlab.

Oh yes sorry I forgot to mention that this was more for the low level API doc for developpers.

Otherwise yes I thinkt that having a good set of jupyter notebooks might be a better "first line of defense" for the documentation on how to use it.

So by with the figure below: jupyter notebook for the top left corner and spinx for the bottom right one.

What do you think?

https://documentation.divio.com/

from bids-matlab.

And I hear you on the mkdocs material being prettier though I am sure we could find a sphinx template for that could feel less... Hum... "Dry".

from bids-matlab.

OK, I agree with you. In terms of priorities, I would focus on the top half of the diagram, even if everything matters at the end of the day.

from bids-matlab.

for maintainability and to lower the barrier for future contributors to the documentation I recommend keeping it as simple as possible. One reason GitHub is so popular is that it natively supports markdown and that you don't have to set up an extra website or CMS system for documentation. So the question here: do we actually need something more sophisticated than a bunch of *.md files?

from bids-matlab.

I think we all agree here: in terms of priority and ease of use sticking to Markdown and jupyter notebook makes sense. For now.

But if we see that we start coying large sections of our code "help" section to reuse in our doc, I will reopen this.

😉 😝

from bids-matlab.