Use MkDocs to generate documentation (#705)

### 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.

```sh
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](https://github.com/quokka-astro/quokka/blob/development/CONTRIBUTING.md).
- [ ] 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.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Ben Wibking <[email protected]>

.github/workflows/docs.yml

@@ -32,9 +32,8 @@ jobs:
 
       - name: Dependencies
         run: |
-          .github/workflows/dependencies/documentation.sh
           python3 -m pip install --upgrade pip
-          python3 -m pip install sphinx==5.3.0 sphinx_rtd_theme sphinxcontrib_bibtex sphinx-copybutton
+          python3 -m pip install pypandoc_binary mkdocs-material>=9.5.9 mkdocs-include-markdown-plugin>=6.0.4 mkdocs-exclude>=1.0.2 mkdocs-macros-plugin>=1.0.4 pymdown-extensions mkdocs-awesome-pages-plugin mkdocs-material mkdocs-bibtex==2.15.0
 
       - name: Install and Build
         run: |
@@ -54,7 +53,7 @@ jobs:
             --exclude=.github \
             .
         env:
-          INPUT_PATH: ./docs/_build/html
+          INPUT_PATH: ./docs/site
 
       - name: Upload artifact
         uses: actions/upload-artifact@main

.gitignore

@@ -38,11 +38,17 @@ __pycache__
 # image files
 *.png
 
+/docs/site/*
+
 # Documentation build directory
 docs/api/
 docs/doxyoutput/
 _build/
 
+# Include image and pdf files inside docs
+!/docs/docs/flowchart-v2.pdf
+!/docs/docs/tests/attach/*.png
+
 # Kokkos build files
 KokkosCore_config.h
 KokkosCore_config.tmp

build_docs.sh

@@ -1,16 +1,7 @@
 #!/bin/bash
 set -e # Exit with nonzero exit code if anything fails
 
-# Doxygen
-echo "Build the Doxygen documentation"
+echo "Build the HTML documentation using MkDocs"
 cd docs
-doxygen &> doxygen.out
-cd ../
-
-# sphinx
-cd docs
-
-echo "Build the Sphinx documentation for Quokka."
-#make PYTHON="python3" LATEXMKOPTS="-interaction=nonstopmode" latexpdf
-make PYTHON="python3" html
+mkdocs build
 cd ../