Add the basic structure of documenter

[seabbs]

For awareness this PR creates the basic Documenter.jl structure (inspired heavily by their approach to their own docs) and will also manage deployment. @SamuelBrand1 good to hear if you think this is going in the right direction and if there is anything we should do differently to the Documenter.jl approach (as I am just implementing that currently).

[SamuelBrand1]

At a glance this looks good.

This is (IMO) an important feature (beautiful docs); I'll do a PR from this branch and try adding some pages using the .jl script -> Documenter flavoured markdown (using Literate) and see what happens when I try and render locally.

The typical environment management is to have a docs environment (iirc), this might just end up being the same as the test env but with Documenter.

[seabbs]

I'll do a PR from this branch and try adding some pages using the .jl script -> Documenter flavoured markdown (using Literate) and see what happens when I try and render locally.

Is this actually the workflow we want or do we want to write these in some quite of true literate format (i.e quarto or similar?). My instinct was that these should be in the docs file and easier to read than interact with as code (i.e favouring having text not as fancy comment strings) but perhaps that isn't where Julia is?

[SamuelBrand1]

I'll do a PR from this branch and try adding some pages using the .jl script -> Documenter flavoured markdown (using Literate) and see what happens when I try and render locally.

Is this actually the workflow we want or do we want to write these in some quite of true literate format (i.e quarto or similar?). My instinct was that these should be in the docs file and easier to read than interact with as code (i.e favouring having text not as fancy comment strings) but perhaps that isn't where Julia is?

Documenter is looking for documenter flavour markdown (I'll call is dfm) to run when you render your documentation (but obviously gfm works too but won't run and then generate plots/output in your documentation) so upstream from that we've got options.

Some options

• My typical workflow: Fancy comment strings in a usual .jl file.
  • Upside: you can just run it from julia from within the doc env to check if it works before rendering to dfm.
  • Downside: You have to be able to read markdown script in your head pretty well.
• Quarto: .qmd file with nice visual mode for rendering markdown along side code chunks.
  • Upside: Nice format, lots of options to render to.
  • Downside: Have to set up Quarto with jupyter to run code blocks. Outputs to gfm so then you'd need to change it to dfm to get the nice documenter features you want.
• Others... Haven't tried so much.

I don't think we need to all do the same workflow to generate the dfm files we want so long as it works?

[seabbs]

Okay for simplicity lets stick with Literate. To get this to be automated though we would need to add a call to Literate.jl in make.jl rather than committing the rendered docs?

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.74%. Comparing base (f55cd6f) to head (f7c5519).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #93   +/-   ##
=======================================
  Coverage   97.74%   97.74%           
=======================================
  Files           6        6           
  Lines         133      133           
=======================================
  Hits          130      130           
  Misses          3        3           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[SamuelBrand1]

This looks great! Really like the doc structure.