Fisher info example

[cs2716]

Closes #194 Update user guide to include reparametrisation process for Fisher information with example of Student's t-distribution

[alejandroschuler]

Yeah sorry it's annoying to do diffs on the documentation given the way it's built at the moment

[alejandroschuler]

@cs2716 @mzjp2 I merged this but it didn't update the docs- this is because the master files for the docs are actually here and I can't remember if you need to locally build the docs before pushing or if it's in the continuous integration... I've been meaning to do a total overhaul of the docs for months now but I haven't gotten around to it. So 3 ways to proceed:

1. continue waiting for me to overhaul the documentation (easiest for you, but timeline indeterminate)
2. figure out how the current documentation is building, implement these changes in the required way, and update this PR (somewhat easy, shouldn't take too long, but won't solve our long-term problem)
3. put in a series of PRs to overhaul the docs (most work for you, but huge contribution to the project- if you want to do this we could also collaborate to publish a paper in the journal of statistical software or something like that)

If you are feeling mighty ambitious and want to take path 3, we should meet up for a little bit to discuss how we're going to stand up both a readthedocs-style API documentation as well as a vignette-style user guide (what we've already got) together in one place with as few redundancies as possible and in a way that's easy to update via simple PRs with obvious diffs so we don't run into these kinds of problems again.

[mzjp2]

@cs2716 @mzjp2 I merged this but it didn't update the docs- this is because the master files for the docs are actually here and I can't remember if you need to locally build the docs before pushing or if it's in the continuous integration... I've been meaning to do a total overhaul of the docs for months now but I haven't gotten around to it. So 3 ways to proceed:

1. continue waiting for me to overhaul the documentation (easiest for you, but timeline indeterminate)
2. figure out how the current documentation is building, implement these changes in the required way, and update this PR (somewhat easy, shouldn't take too long, but won't solve our long-term problem)
3. put in a series of PRs to overhaul the docs (most work for you, but huge contribution to the project- if you want to do this we could also collaborate to publish a paper in the journal of statistical software or something like that)

If you are feeling mighty ambitious and want to take path 3, we should meet up for a little bit to discuss how we're going to stand up both a readthedocs-style API documentation as well as a vignette-style user guide (what we've already got) together in one place with as few redundancies as possible and in a way that's easy to update via simple PRs with obvious diffs so we don't run into these kinds of problems again.

Hey Alejandro, I'm happy to work with you to setup a readthedocs-style documentation (I helped build large parts of https://kedro.readthedocs.io/en/stable/).

But maybe it's worth doing both 2 & 3? I'll have a look and see how much work 2 is tonight and if it's worth doing as a bandaid before doing 3.

[ryan-wolbeck]

@alejandroschuler You need to build locally before committing changes to the docs. @tonyduan can probably provide insight here. I generally agree that option 3 should be a priority and it would be great if you took that on @mzjp2

[mzjp2]

@tonyduan would be super helpful to hear what the process is. I've spent an hour trying to investigate and am incredibly confused as to why there's multiple copies of the jupyter notebooks in docs/content and examples/user-guide/content with slight differences between them. The Makefile within both docs/ and example/user-guide also seem to have incorrect commands (at least with the version of jupyter-book that got installed for me). Not sure how to build these docs or which docs to build!

[alejandroschuler]

@mzjp2 yeah, this is part of why I think it might be better to just redo the docs altogether. JupyterBook had a major update a few months ago and we're still on the old version so the build process is a little different.

I just remembered I have a git pre-commit hook to rebuild the docs. Here is the relevant snippet:

os.system('jupyter-book build examples/user-guide')
os.chdir('examples/user-guide')
os.system('bundle exec jekyll build --destination ../../docs')
os.chdir('../../')
os.system('git add docs')
os.system('git add examples/user-guide')

So basically what you need to do is

1. update the .ipynb files in examples/user-guide/content
2. build the book (having jupyter book installed- perhaps an older version!?): jupyter-book build examples/user-guide
3. build the static site: bundle exec jekyll build examples/user-guide --destination ../../docs (the output has to go in docs because that's how github's static site hosting needs it to work- at least that's how it was a few months ago)
4. git add docs and git add examples/user-guide to update the repo
5. commit and push. Github actions will rebuild the static site and host it.

[tonyduan]

@mzjp2 Just saw this, thanks for the help! What Alejandro said is accurate; unfortunately in the past I've resorted to the same series of (somewhat) manual steps. It's definitely on the backlog to overhaul...