Add basic documentation site

[melissawm]

@SwayamInSync so sorry it took me so long!!

Here's a basic docs site setup. I haven't set up the website yet, but I can give you instructions later. Here's a preview of how the site looks like right now: https://melissawm.github.io/numpy-user-dtypes/

[juntyr]

Would it be possible to add an updated version of the release tracker table to the docs? This would be a great place to list all supported ufuncs and where we could later document e.g. the ULPs for each function

[SwayamInSync]

Thanks @melissawm

@juntyr yeah we will extend this, to add all those details

[SwayamInSync]

@ngoldbaum (didn't explored in deep yet) Would this startup setup be extendable to your work (https://unyt.readthedocs.io/en/stable/)

[ngoldbaum]

Yeah, unyt also uses sphinx. It doesn't use myst because unyt predates myst.

I would defer to Melissa's setup. Maybe look at unyt if you're interested in setting up doctesting.

[juntyr]

@SwayamInSync Should we just merge this in for 1.0?

[SwayamInSync]

I was having some plans for this actually,
@ngoldbaum please correct me if I'm wrong but can't the doc's versoning and package's versioning go independently?

[ngoldbaum]

You can but I wouldn't recommend it. It's much better IMO for doc changes to happen at the same time as code changes.

My recommendation is to merge this, set up a docs site on github pages or readthedocs, and iterate from there.

[SwayamInSync]

You can but I wouldn't recommend it. It's much better IMO for doc changes to happen at the same time as code changes.

My recommendation is to merge this, set up a docs site on github pages or readthedocs, and iterate from there.

Sure then, I'll resolve its conflict and merge in after #246

[melissawm]

Let me know if I can help!

[SwayamInSync]

Hi @melissawm yeah so should I merge this and then you can guide me on setting up the site?
Was thinking of readthedocs?

[melissawm]

RTD is a fine option, but we could also go with a simple github pages site. Happy to submit a workflow here for that. Wdyt?

To help with the decision here are the options:

• RTD: needs a readthedocs.yml file and creating a new project on readthedocs.io connecting to this repo.
• Github Pages: needs a build_docs.yaml file in the .github/workflows folder and enabling github pages in this repo.

Both yaml files are very simple and I can set up either.

[SwayamInSync]

The github one sounds more direct, we can go with that then.

[juntyr]

Readthedocs has the advantage of preserving all versions of the docs so that you can look back

[melissawm]

The pydata-sphinx-theme also has a built in version switcher, it's just not activated yet but I can do that. In that case, both options would have a version switcher.

It's your call really, I'd recommend github pages just because all the config and deployment is centralized in github and all repo admins will be able to manage that. For RTD, that's a separate login, separate list of admins etc

[SwayamInSync]

I think we can go with gh-pages for now, at this point content matters more and having everything right here will be easier to iterate

[melissawm]

Let me push the config then! I'll enable pages for the repo too. Will ping you once it's ready

[melissawm]

@SwayamInSync this is now ready to merge. The GH action to build and deploy pages will not work unless it's merged to main, but I'm pretty confident it will work (tested locally). Cheers!

[SwayamInSync]

Thanks a lot @melissawm , this look good to me,
Just a small question here, I am also okay with the current address

[SwayamInSync]

Just a curious question, is it possible to route it to numpy.github.io/numpy-user-dtypes/quaddtype ?

[melissawm]

Sure, we can add a redirect. Let me test and see what's the best approach here

[melissawm]

Done!

[ngoldbaum]

Another thing that may be worth considering: has quaddtype outgrown this repo? Maybe it deserves to have its own repo in the NumPy org on GitHub.

[SwayamInSync]

Another thing that may be worth considering: has quaddtype outgrown this repo? Maybe it deserves to have its own repo in the NumPy org on GitHub.

I feel this true, the current codebase ~15K Lines (If also consider QBLAS then 20K) so I think yeah maybe as all the current PRs get resolved, it can be shifted to its own repo, also its weird to clone all dtypes just to work on quaddtype xD

We do again have to setup the PyPI env quadtype_release and I don't think any other changes will be needed on repo level

[ngoldbaum]

A downside is it would lose the old PR numbers, although they’ll live on in this repo.

We’ll have to make sure to export the history in a way that preserves all the commits - it’s not great for git history to start with a huge codebase.

[SwayamInSync]

A downside is it would lose the old PR numbers, although they’ll live on in this repo.

We’ll have to make sure to export the history in a way that preserves all the commits - it’s not great for git history to start with a huge codebase.

git-history can be cloned, but the individual PRs might be harder to port. Here all PRs have the label numpy_quaddtype so we can scrape and create a single issue/discussion that maps back to the PR link 🤷‍♂️

[juntyr]

At least issues can be transferred to a new repo?

[melissawm]

If the plan is to move repos, do you still want the redirect?

[melissawm]

This should work :) Locally it does: https://melissawm.github.io/numpy-user-dtypes/quaddtype/

[SwayamInSync]

Ah I will later also remove the docs folder from testing CI's path, as these tests aren't required here

[SwayamInSync]

Thanks again @melissawm this is good, I am going ahead to merge this.
And will take care of the changes in the docs when porting the repo :)

[melissawm]

Oh yeah, I forgot : we actually get the nice numpy.org domain 😁

https://numpy.org/numpy-user-dtypes/quaddtype/