Improve documentation building

- [ ] stricter checks
- [ ] bibtex

# Stricter checks

the documentation should be built with stricter error checking
```bash
        make html SPHINXOPTS="-W --keep-going -n"
```

this should be part of the CI pipeline, not part of the read the docs process.


# Bibtex

It should use bibtex for references.
https://sphinxcontrib-bibtex.readthedocs.io/en/latest/