search

hyanwong / giglib

MIT License
4 stars 2 forks source link

Documentation via JupyterBook (and tidy) #106

Open hyanwong opened 7 months ago

hyanwong commented 7 months ago

We are getting to the point where we could create some documentation for GIGL.

I think it would be easiest to follow the tskit scheme and use JupyterBook (e.g. as in https://github.com/tskit-dev/tsdate). However, I'm not sure where we would host the docs. I guess on GitHub Pages for the time being. I suspect I will need to get Ben Jeffery to help me set this up.

hyanwong commented 7 months ago

Chances are we will need to do a lot of tidying of docstrings etc to get this looking even halfway acceptable. I guess you would be happy to help with this @duncanMR ? Seems a good way to check over the API we have come up with.

duncanMR commented 7 months ago

Sure, I'd be happy to edit the docstrings!

hyanwong commented 7 months ago

@duncanMR: I have added the infrastructure for building to the /docs directory now. Type make in there (after pip install -r requirements.txt), and you should be able to look at the skeleton docs in _build/html/index.html, I hope.

I guess you'll mainly need to edit the python-api.md file. You can look at how things are done in tskit by looking at https://github.com/tskit-dev/tskit/blob/main/docs/python-api.md

I will need to set up a Github action to upload the html files e.g. to a GitHub pages URL. I'm not sure how the version numbering will work here, and will ask Ben Jeffery.

duncanMR commented 7 months ago

Okay, I'll take a look. I will check if the docstrings I've already written render correctly

hyanwong commented 7 months ago

Thanks. I'm not sure they are actually listed there yet - some fiddling with the python-api.md file will probably be required. But useful for you to figure out how this works, as it's basically the same setup as for the tskit etc. docs.