Start writing docs.

[mkcor]

Hi @lagru,

Here I'm starting some minimal documentation as per #9.

I'm using the same structure and formats as scikit-image's so we can use the same machinery to build the docs, i.e., generated the rendered HTML pages. I guess we should deploy these somewhere?

I've noticed that

• the scikit-image docs live at https://scikit-image.org/docs/stable/ while
• the NumPy docs live at https://numpy.org/doc/stable/ (no -s).

Maybe it would be more consistent to have doc/src/index.rst instead of doc/source/index.rst?

[lagru]

Thanks for getting this going @mkcor!

I've been thinking about how to keep the effort for the documentation infrastructure low during early development. E.g. start with a Wiki on the Repo? I'm also considering to go "full markdown" for docstubs documentation via MyST?

I'm curious what you think.

Maybe it would be more consistent to have doc/src/index.rst instead of doc/source/index.rst?

I've never really been a fan of the extra doc/source/ folder / level in scikit-image and would love to avoid it here if we can.

[mkcor]

Hi @lagru!

I've never really been a fan of the extra doc/source/ folder / level in scikit-image and would love to avoid it here if we can.

I totally agree, doc/index.rst should be good enough!

I've been thinking about how to keep the effort for the documentation infrastructure low during early development. E.g. start with a Wiki on the Repo? I'm also considering to go "full markdown" for docstubs documentation via MyST?

Nice, I like being minimalist. Good idea; let's keep the docs in the repo's wiki, at least for now. We can always move them later, and they'll be in Markdown already.

PS: I found out about MyST last year at JupyterCon and would love a pretext to try it out!

[mkcor]

@lagru would you mind creating the wiki for this repo? I personally don't have access to the 'Settings' tab... I guess that's where you can check the box to get the Wiki. Thanks!

[mkcor]

would you mind creating the wiki for this repo?

Or, alternatively, give me permission to do so? Any update on this, @lagru? Thanks.

[lagru]

Oh, I didn't realize that you needed write permissions. I granted you those, but maybe its easiest to just commit the markdown files in the main repo instead of taking the detour via wiki. We can worry about the plumbing for a HTML documentation later.

That way your contributions are more visible also, stay preserved and we have a proper review process. :)

[mkcor]

maybe its easiest to just commit the markdown files in the main repo

You're right.

That way your contributions are more visible also, stay preserved and we have a proper review process. :)

Very valid point! Good, I'll update this PR then, and mark it as ready for review.

[mkcor]

@lagru the action is happening at 699c509

[mkcor]

I don't know how to insert a variable in here...

[mkcor]

I don't know how to insert a variable in here...

[mkcor]

For now, we could hard-write it.

[lagru]

Honestly, I think we can skip this for now. It should be pretty clear that the user guide reflects the current version of the repo. Longterm this should end up in a website with a version switcher anyway. :)

[lagru]

@mkcor, do you mind if I go through this PR and tweak and update as you go? I think that might be the fastest approach to fleshing out this guide some more. After that we can have another round of iteration. I'd be especially thankful for your eyes which are less familiar with the inner workings!

[mkcor]

I don't mind at all, please go ahead!