Use MkDocs to generate documentation

[chongchonghe]

Description

Use MkDocs to generate the documentation page, replacing Sphinx.

I tested it on my computer with the following steps and it worked perfectly fine. Not guaranteed to work on github. May need your help @BenWibking to update the docs.yml properly.

cd docs2
python -m pip install -r requirements.txt
mkdocs build && mkdocs serve

Currently all the new docs are in docs2. Once everything works fine, I'll use it to replace docs.

Related issues

Closes #542

Checklist

Before this pull request can be reviewed, all of these tasks should be completed. Denote completed tasks with an x inside the square brackets [ ] in the Markdown source below:

• I have added a description (see above).
• I have added a link to any related issues see (see above).
• I have read the Contributing Guide.
• I have added tests for any new physics that this PR adds to the code.
• I have tested this PR on my local computer and all tests pass.
• I have manually triggered the GPU tests with the magic comment /azp run.
• I have requested a reviewer for this PR.

[BenWibking]

It looks like there are some missing images:

WARNING -  Doc file 'flowchart.md' contains a link 'flowchart-v2.pdf', but the target is not found among documentation files.
WARNING -  Doc file 'tests/energy_exchange.md' contains a link 'attach/radcoupling_rsla.png', but the target
           'tests/attach/radcoupling_rsla.png' is not found among documentation files.
WARNING -  Doc file 'tests/energy_exchange.md' contains a link 'attach/radcoupling.png', but the target 'tests/attach/radcoupling.png' is not
           found among documentation files.
WARNING -  Doc file 'tests/radhydro_pulse.md' contains a link 'attach/radhydro_pulse_temperature-1.png', but the target
           'tests/attach/radhydro_pulse_temperature-1.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_pulse.md' contains a link 'attach/radhydro_pulse_density-1.png', but the target
           'tests/attach/radhydro_pulse_density-1.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_pulse.md' contains a link 'attach/radhydro_pulse_velocity-1.png', but the target
           'tests/attach/radhydro_pulse_velocity-1.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_pulse.md' contains a link 'attach/radhydro_pulse_temperature.png', but the target
           'tests/attach/radhydro_pulse_temperature.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_pulse.md' contains a link 'attach/radhydro_pulse_density.png', but the target
           'tests/attach/radhydro_pulse_density.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_pulse.md' contains a link 'attach/radhydro_pulse_velocity.png', but the target
           'tests/attach/radhydro_pulse_velocity.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_uniform_adv.md' contains a link 'attach/radhydro_uniform_advecting_temperature.png', but the target
           'tests/attach/radhydro_uniform_advecting_temperature.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_uniform_adv.md' contains a link 'attach/radhydro_uniform_advecting_velocity.png', but the target
           'tests/attach/radhydro_uniform_advecting_velocity.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_uniform_adv.md' contains a link 'attach/radhydro_uniform_advecting_temperature-nobeta.png', but the
           target 'tests/attach/radhydro_uniform_advecting_temperature-nobeta.png' is not found among documentation files.
WARNING -  Doc file 'tests/radhydro_uniform_adv.md' contains a link 'attach/radhydro_uniform_advecting_velocity-nobeta.png', but the target
           'tests/attach/radhydro_uniform_advecting_velocity-nobeta.png' is not found among documentation files.
WARNING -  Doc file 'tests/radshock.md' contains a link 'attach/radshock_cgs_temperature.png', but the target
           'tests/attach/radshock_cgs_temperature.png' is not found among documentation files.
WARNING -  Doc file 'tests/shu_osher.md' contains a link 'attach/hydro_shuosher.png', but the target 'tests/attach/hydro_shuosher.png' is not
           found among documentation files.
WARNING -  Doc file 'tests/sms.md' contains a link 'attach/hydro_sms.png', but the target 'tests/attach/hydro_sms.png' is not found among
           documentation files.

[BenWibking]

The links don't work in the version generated on GitHub...

Ok, this is just because I downloaded them and opened the files in the web browser, which doesn't redirect links to the subdirectories to subdir/index.html. I think this is not actually an issue.

[BenWibking]

@chongchonghe Can you fix the missing images? I'm guessing you just forgot to git add them to the PR.

[chongchonghe]

@BenWibking Can you test it now? Should work now.

[chongchonghe]

@BenWibking How do you see the html files/pages rendered by github before merging this to the development branch?

[BenWibking]

@BenWibking How do you see the html files/pages rendered by github before merging this to the development branch?

You can download the artifact listed at the bottom of this page: https://github.com/quokka-astro/quokka/actions/runs/10293768978?pr=705

[BenWibking]

The "test problems" renders as its own chapter:

Is there a way to get it to render as a drop-down menu like before?

[BenWibking]

Otherwise, it looks fine to me. Can you replace the old docs/ folder with docs2?

[chongchonghe]

@BenWibking How do you see the html files/pages rendered by github before merging this to the development branch?

You can download the artifact listed at the bottom of this page: https://github.com/quokka-astro/quokka/actions/runs/10293768978?pr=705

Awesome!

[chongchonghe]

The "test problems" renders as its own chapter:

Is there a way to get it to render as a drop-down menu like before?

I don't know a way to do it. The menus are controlled in mkdocs.yml, and they are either all expanded or all collapsed by default. Can we leave it as is for now and deal with it later? Currently there aren't many test problems so this is probably fine. Next, I will try to merge all test problems into one single page, and add a TOC inside that page for quick navigation. That are themes that does that automatically.

[chongchonghe]

The links don't work in the version generated on GitHub...

Ok, this is just because I downloaded them and opened the files in the web browser, which doesn't redirect links to the subdirectories to subdir/index.html. I think this is not actually an issue.

Right. You need a local server to view it with working links. You can do this via python -m http.server inside the folder.

[BenWibking]

The links don't work in the version generated on GitHub...
Ok, this is just because I downloaded them and opened the files in the web browser, which doesn't redirect links to the subdirectories to subdir/index.html. I think this is not actually an issue.

Right. You need a local server to view it with working links. You can do this via python -m http.server inside the folder.

Ah, yeah, I realized that. Everything looks good to me now.

[BenWibking]

Except for the .gitignore file. I think the leading / may make it think those are absolute paths.