Write developer docs on demos

[jwallwork23]

We need detailed instructions on how to build the docs, as well as to tell both PR authors and reviewers to check they build successfully.

Perhaps we could also introduce CI tests to check sphinx formatting?

[ddundo]

Good idea. Maybe we could then try to separate out different modules here? At the moment a developer working only on animate still must install goalie and movement, and run all their demos, before being able to build the docs.

[jwallwork23]

Maybe we could then try to separate out different modules here? At the moment a developer working only on animate still must install goalie and movement, and run all their demos, before being able to build the docs.

Sorry, please could you clarify what you mean by "separate out different modules here"?

[ddundo]

Sorry, please could you clarify what you mean by "separate out different modules here"?

Sorry, I imagined this as something like passing an optional argument to make html, e.g. make html module=animate which would only build the animate part of the docs. This would obviously not be a fully functional website build, but good enough for the developer to check locally that relevant things are working as they should.

My point is that if we require developers to build the docs, I think that we should make this as simple as we can. At the moment building docs requires installing all 3 modules (animate, goalie, movement) and takes about an hour since we have to run all their demos.

[jwallwork23]

Hm okay good point. Yeah could probably do something like that.

[ddundo]

@jwallwork23 actually, is there a reason why demos are not Jupyter notebooks? I think this might be both more user-friendly and developer-friendly, since it wouldn't require building the docs to check the formatting of the notebook etc.

[jwallwork23]

I prefer not to include Jupyter notebooks in repos because

• They have a large memory footprint.
• You get enormous diffs with very difficult to read changes whenever anyone edits one of them.
• These diffs also include lots of details that are specific to the machine you are building on.
• Once you have a couple of Jupyter notebooks in your repo they are big enough that GitHub thinks Jupyter is the main language in your repo.

[ddundo]

Ah okay, thanks for explaining this! I didn't know :)