Switch to documenteer guide doc build

[timj]

No description provided.

[timj]

@jonathansick as discussed in #1081 I had a go at switching to the new documenteer guide. It sort of works but the bibtex stuff fails:

reading sources... [100%] templates/presentation
[55](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:56)
/home/runner/work/lsst-texmf/lsst-texmf/docs/examples/MEMO-nnn.rst:5: WARNING: duplicate label dmtn-nnn, other instance in /home/runner/work/lsst-texmf/lsst-texmf/docs/examples/DMTN-nnn.rst
[56](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:57)
/home/runner/work/lsst-texmf/lsst-texmf/docs/index.rst:5: ERROR: Unknown interpreted text role "cite".
[57](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:58)
/home/runner/work/lsst-texmf/lsst-texmf/docs/index.rst:5: ERROR: Unknown interpreted text role "cite".
[58](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:59)
/home/runner/work/lsst-texmf/lsst-texmf/docs/index.rst:5: ERROR: Unknown interpreted text role "cite".
[59](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:60)
/home/runner/work/lsst-texmf/lsst-texmf/docs/lsstdoc.rst:107: ERROR: Unknown interpreted text role "cite".
[60](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:61)
/home/runner/work/lsst-texmf/lsst-texmf/docs/references.rst:7: ERROR: Unknown directive type "bibliography".
[61](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:62)

[62](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:63)
.. bibliography:: ../texmf/bibtex/bib/lsst.bib
[63](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:64)
   :style: lsst_aa
[64](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:65)
looking for now-outdated files... none found
[65](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:66)
pickling environment... done
[66](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:67)
/home/runner/work/lsst-texmf/lsst-texmf/docs/_templates/README.md: WARNING: document isn't included in any toctree
[67](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:68)
checking consistency... done

(although the build reports success) and no citations render. The menu also looks bad across the top of the page rather than being on the side like it was before. Does guide support bibtex?

[jonathansick]

The menu also looks bad across the top of the page rather than being on the side like it was before.

Yes, the new theme has a three-level navigational hierarchy. You'll need to rearrange the toctree directives a bit to make things work. See https://documenteer.lsst.io/guides/organization.html

One thing I need to still mention in that guide is you can rename a "part" along the top bar to a shorter name than the natural page name by giving it a short name in the toctree. For example:

.. toctree::
   :hidden:

   Guide <user-guide/index>
   Releases <changelog>

---

/home/runner/work/lsst-texmf/lsst-texmf/docs/_templates/README.md: WARNING: document isn't included in any toctree
[67](https://github.com/lsst/lsst-texmf/actions/runs/8607017732/job/23586665846#step:11:68)

This is happening because Markdown files are now eligible as content. You can exclude that content using [sphinx.exclude] in documenteer.toml:

[sphinx]
exclude = [
  "_templates/README.md"
]

---

Does guide support bibtex?

Not out of the box. I added some review comments with the rest of the configuration.

[timj]

@jonathansick thanks for the fixes. However many toctrees I have it doesn't change the top bar. I don't really want a top bar at all -- the navigation on the left of all the sections was fine before. The documentation you linked to implied that if I group my pages with separate toctree lines then it would change the top bar but I must be doing something wrong because it has no effect and just adds a heading to the index page.

[timj]

@jonathansick I've had another go but even if I manage to get smaller titles for the top of the top page, each lower page still gets the longer titles. The main document title also runs over the top menu bar.

[jonathansick]

I'll make a PR based on this PR with the organization I have in mind. That'll be easier than trying to describe it.