Discussion: docs framework and location

[kevinyamauchi]

I wanted to start the discussion here about the docs. I will have time to work on this in the coming weeks, so it might be nice to get some agreement on (1) which framework we want to use and (2) where we want to deploy them.

I've listed some thoughts below to get the conversation started.

Frameworks:

• sphinx:
  • too complicated for me 😛
• jupyterbook:
  • more friendly than sphinx
  • has the possibility of running/rendering notebooks on CI
  • getting the notebooks to run on CI can be a bit annoying
  • example: site, repo
• mkdocs:
  • probably the simplest I've seen
  • example: site, repo

Deploy location:

• readthedocs:
  • As pointed out in #49, https://spatialdata.readthedocs.io/en/latest/ is taken.
• github.io:
  • free
  • maybe not the best url scverse.github.io/spatialdata
• scverse.org:
  • I think this would be the nicest.
  • I'm not sure how the scverse.org site is setup and how difficult this would be

[ivirshup]

Frameworks

For scverse stuff we use sphinx, but are moving more and more towards the jupyterbook side of things since it just makes working with sphinx so much more accessible. (jupyterbook all on top of sphinx though, right @kevinyamauchi?)

So sphinx, but with myst, and the newer, kinder, generation of extensions.

Deployment

So, once could in theory host something on github pages and have it appear at whatever domain under scverse. We have been meaning to do this for scirpy, but haven't had the (1) person who controls the domain, (2) person who understands how github pages work and (3) person who understands how domains work all remembering we want to do this, and being free at the same time to set it up.

Readthedocs provides some very nice features (PR builds, multiple versions of docs), so if possible I would still try to at least use them for hosting/ building. I believe one should also be able to host docs at readthedocs, but make them available through the scverse domain: https://docs.readthedocs.io/en/stable/custom-domains.html.

[kevinyamauchi]

Thanks for the reply, @ivirshup !

For scverse stuff we use sphinx, but are moving more and more towards the jupyterbook side of things since it just makes working with sphinx so much more accessible. (jupyterbook all on top of sphinx though, right @kevinyamauchi?)

Yes, I was referring to jupyterbook on top of sphinx. I agree jupyterbook is much more friendly than bare sphinx. I'm happy to move forward with jupyterbook if that's what scverse is using. I think there's value in unifying to reduce maintenance overhead.

If you haven't already, I would recommend checking out mkdocs. I was previously a jupyterbook user, but I've been making all new docs with mkdocs. I find it even simpler to use. However, it's not so much simpler that I'd say it's worth converting all existing scverse docs from jupyterbook to mkdocs at this point - maybe just something to consider for the future.

I will have time the week of December 12. I can start on the docs then if nobody has gotten to it yet.

Readthedocs provides some very nice features (PR builds, multiple versions of docs), so if possible I would still try to at least use them for hosting/ building. I believe one should also be able to host docs at readthedocs, but make them available through the scverse domain: https://docs.readthedocs.io/en/stable/custom-domains.html.

I believe @giovp snagged https://scverse-spatialdata.readthedocs.io/en/latest/ (https://github.com/scverse/spatialdata/pull/50#issuecomment-1326270282). Perhaps we can start deploying the docs there and then change if/when we figure out the scverse.org thing. I know how to deploy docs to www.org-name.github.io/repo-name. I think this works with custom domains, but I'm not 100% sure. We could give it a go at some point.

[ivirshup]

I think we've also updated the scverse template since this repo was created to use more of the Jupyter book stuff (e.g. myst-nb, and a jupyterbook-y theme). @giovp, should we generate at least the docs of this package from the current template?

If you haven't already, I would recommend checking out mkdocs.

My main inclination would be to not learn another static site generator 😉. sphinx and hugo are painful enough.

[kevinyamauchi]

Okay, since there's an updated jupyterbook template, I'll wait for @giovp to update before working on the docs. Alternatively, if somebody can point me to instructions, I can do it.

Regarding yet another docs website generator: fair enough 😂

[ivirshup]

Btw, just got subdomains working on scverse.org, so we have [muon.scverse.org]().

Maybe spatialdata.scverse.org/docs/ could point to a readthedocs hosted site for this?

[giovp]

that'd be great, how do I make readthedocs point to spatialdata.scverse.org/docs/ ?

[ivirshup]

Hmm, it's looking like it may be a little difficult to do spatialdata.scverse.org/docs – I think it would be possible with a server, but we'd have to set that up. Easier would be:

• spatialdata.scverse.org – which would be done with a CNAME record
• docs.scverse.org/projects/spatialdata which would be a CNAME record + readthedocs subprojects

There's some appeal to docs.scverse.org/projects/spatialdata to me if we use docs.scverse.org for the project wide tutorials we worked on during the hackathon. But way back when I think we said we wanted to do project specific subdomains, so idk. (cc: @grst)

[ivirshup]

Discussion was brought up again at: https://scverse.zulipchat.com/#narrow/stream/322546-media/topic/scverse.20core.20tools.20domains