Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch to documenteer guide doc build #1089

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Switch to documenteer guide doc build #1089

wants to merge 8 commits into from

Conversation

timj
Copy link
Member

@timj timj commented Apr 8, 2024

No description provided.

@timj timj force-pushed the u/timj/sphinx-guide branch 2 times, most recently from cda48e2 to 49a4566 Compare April 8, 2024 21:44
@timj
Copy link
Member Author

timj commented Apr 8, 2024

@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?

docs/documenteer.toml Show resolved Hide resolved
docs/conf.py Show resolved Hide resolved
@jonathansick
Copy link
Member

jonathansick commented Apr 8, 2024

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
Copy link
Member Author

timj commented Apr 8, 2024

@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
Copy link
Member Author

timj commented Apr 26, 2024

@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
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants