Jupyter-book build errors

[da5nsy]

Getting some fun* errors currently in building the jupyter book locally.
* where "fun" = not serious but we should work through them.

I'll put the raw output here and then we can spin out individual issues/PRs for each one as we see fit.

Here's the raw output:

←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\afterword\glossary.md:3: WARNING: glossary term must be preceded by empty line←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\afterword\glossary.md:9: WARNING: glossary term must be preceded by empty line←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\afterword\glossary.md:21: WARNING: glossary term must be preceded by empty line←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\afterword\glossary.md:27: WARNING: glossary term must be preceded by empty line←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\afterword\glossary.md:3: WARNING: glossary term must be preceded by empty line←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\communication\open.md:1: WARNING: duplicate label evolution-open-research, other instance in C:\Users\cege-user\Documents\the-turing-way\book\website\reproducible-research\open.md←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\communication\open.md:21: WARNING: duplicate label rr-open-summary, other instance in C:\Users\cege-user\Documents\the-turing-way\book\website\reproducible-research\open.md←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\community-handbook\community-handbook.md:: WARNING: toctree contains reference to nonexisting document 'community-handbook/contributing' [etoc.ref]←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\ethical-research\ethics-open-source-governance.md:107: WARNING: Duplicate explicit target name: "er-ethics-open-source-governance-summary".←[39;49;00m
←[91mWARNING: unknown directive or role name: ref:ps←[39;49;00m
←[31mC:\Users\cege-user\Documents\the-turing-way\book\website\project-design\sdp\pd-sdp-private-learning.md:32: ERROR: Unknown interpreted text role "ref:ps".←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\project-design\sdp\types.md:2: WARNING: Non-consecutive header level increase; 0 to 2 [myst.header]←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\project-design\sdpm\informed.md:2: WARNING: Non-consecutive header level increase; 0 to 3 [myst.header]←[39;49;00m
←[91mWARNING: unknown directive or role name: ref:ps←[39;49;00m
←[31mC:\Users\cege-user\Documents\the-turing-way\book\website\project-design\sdpw\pd-sdp-private-learning.md:32: ERROR: Unknown interpreted text role "ref:ps".←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\reproducible-research\open.md:1: WARNING: duplicate label evolution-open-research, other instance in C:\Users\cege-user\Documents\the-turing-way\book\website\communication\open.md←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\reproducible-research\open.md:21: WARNING: duplicate label rr-open-summary, other instance in C:\Users\cege-user\Documents\the-turing-way\book\website\communication\open.md←[39;49;00m
←[31mC:\Users\cege-user\Documents\the-turing-way\book\website\reproducible-research\open\open-access.md:106: ERROR: Directive 'figure': Invalid options YAML: while scanning a simple key
  in "<unicode string>", line 4, column 1:
    The **gold and diamond** routes  ...
    ^
could not find expected ':'
  in "<unicode string>", line 5, column 1:

    ^

---
height: 500px
name: routes-to-OA
alt: An image of a train showing the routes to open access publishing. The green route is signalled as free and shows a preprint server at the start of the journey and self archive at the end.
The **gold and diamond** routes are signalled as author pay and funder or institution pay and show the publish in an open access journal part of the journey.
---
Routes to publishing openly.
_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. Original version on Zenodo. [http://doi.org/10.5281/zenodo.5706310](http://doi.org/10.5281/zenodo.5706310)←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\afterword\bibliography.md:6: WARNING: missing journal in kairouzAdvancesOpenProblems2019←[39;49;00m
←[01mlooking for now-outdated files... ←[39;49;00m55 found
←[01mpickling environment... ←[39;49;00mdone
←[01mchecking consistency... ←[39;49;00m←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\communication\new-articles.md: WARNING: document isn't included in any toctree←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\community-handbook\contributing\contributing-templates.md: WARNING: document isn't included in any toctree←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\community-handbook\contributing\contributing-workflow.md: WARNING: document isn't included in any toctree←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\figures\_figure-list.md: WARNING: document isn't included in any toctree←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\project-design\sdp\pd-sdp-private-learning.md: WARNING: document isn't included in any toctree←[39;49;00m
done
←[01mpreparing documents... ←[39;49;00mdone
←[01mwriting output... ←[39;49;00m[100%] ←[32mwelcome←[39;49;00m                                               0m00m00m39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\collaboration\research-infrastructure-roles\data-steward.md:53: WARNING: undefined label: cl-infrastructure-datastewards-support←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\communication\new-articles.md:19: WARNING: undefined label: chapter-label←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\communication\peer-review\peer-review-overview.md:14: WARNING: undefined label: rr-open-access-whatis-publishing←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\community-handbook\acknowledgement.md:19: WARNING: undefined label: contributors-record-contributors←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\community-handbook\acknowledgement\acknowledgement-members.md:12: WARNING: undefined label: contributors-record-contributors←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\community-handbook\acknowledgement\acknowledgement-record.md:4: WARNING: undefined label: contributors-record-contributors←[39;49;00m
←[91mC:\Users\cege-user\Documents\the-turing-way\book\website\reproducible-research\renv\renv-containers.md:550: WARNING: Could not lex literal_block as "bash". Highlighting skipped.←[39;49;00m

Individual Issues:

• [BUG] jupyter-book build warning - "WARNING: glossary term must be preceded by empty line" #2612
• Duplicate labels #2618
• typo which breaks reference #2620
• bash syntax highlighting error on reproducible-research/renv/renv-containers #2639
• add journal field to supress jupyter-book warning #2621
• typo which breaks reference #2620
• Fix referencing syntax #2640
• fix broken alt text formatting (must be on one line) #2672
• Broken internal links on communication/peer-review/peer-review-overview #2673
• Community Handbook issues #2674
• Correct top header levels in project design guide #2686
• Restore contributing chapter #2689

[aleesteele]

@da5nsy, love the caretaking tags. Thanks so much for the importance maintenance work you are doing right now with The Turing Way. I wonder if some of the folks who were at the Jupyter conversation at Collaboration Cafe could join in here? Or if there are any other folks interested in building the book locally (that have yet to get involved in project infrastructure) that could be involved here?

We can add a room at an upcoming Collaboration Cafe to talk more about it, maybe at the one on the 20th if you're interested & available. I'm beginning to wonder if there should be an ongoing infrastructure room at Collab Cafes, or a separate recurring call.

--

Also flagging that I spoke to @aldenc today about how we can build better issue templates around reporting bugs & infrastructure issues. She's opening a room at Collab Cafe to do some user testing tomorrow, so if you're free to attend tomorrow, maybe you could speak with her about it? 😊

[da5nsy]

Thanks @aleesteele! I'm not certain that caretaking is the perfect word, but it fills what felt like a gap to me well enough for now 😊
I'll slowly work through what I can here, and then anything that's beyond me I'll start picking brains!
If anyone jumps in before me and cleans out any of these before I get there I'll be very happy about it of course! :)

I'll try to swing by tomorrow!

[bsipocz]

I would strongly suggest that once all these issues are fixed, change the CI so the jobs would fail with any errors (or even better, any warnings) raised during the build.
It may be a bit annoying on the content PRs, but it would help a lot to not accumulate the issues listed above. While some of them are down to formatting things the way the build system likes it, others of duplicate or missing references are very much affecting the correctness of the content, too.

[da5nsy]

I would strongly suggest that once all these issues are fixed, change the CI so the jobs would fail with any errors (or even better, any warnings) raised during the build. It may be a bit annoying on the content PRs, but it would help a lot to not accumulate the issues listed above. While some of them are down to formatting things the way the build system likes it, others of duplicate or missing references are very much affecting the correctness of the content, too.

@bsipocz - How would we go about doing this?

[bsipocz]

There is a nitpicky mode for sphinx, but I'll have to check how that can be applied to this setup (as opposed to library API docs building where it works out of the box) I'll try to find some time later this week for a small pr.

[da5nsy]

Updated output (formatting edited for clarity):

• \the-turing-way_main\book\website\community-handbook\community-handbook.md:: WARNING: toctree contains reference to nonexisting document 'community-handbook/contributing' [etoc.ref]←[39;49;00m
• \the-turing-way_main\book\website\communication\new-articles.md: WARNING: document isn't included in any toctree←[39;49;00m
• \the-turing-way_main\book\website\community-handbook\contributing\contributing-templates.md: WARNING: document isn't included in any toctree←[39;49;00m
• \the-turing-way_main\book\website\community-handbook\contributing\contributing-workflow.md: WARNING: document isn't included in any toctree←[39;49;00m
• \the-turing-way_main\book\website\figures_figure-list.md: WARNING: document isn't included in any toctree←[39;49;00m
• \the-turing-way_main\book\website\project-design\sdp\pd-sdp-private-learning.md: WARNING: document isn't included in any toctree←[39;49;00m
• \the-turing-way_main\book\website\community-handbook\acknowledgement.md:19: WARNING: undefined label: contributors-record-contributors←[39;49;00m
• \the-turing-way_main\book\website\community-handbook\acknowledgement\acknowledgement-record.md:4: WARNING: undefined label: contributors-record-contributors←[39;49;00m

Lots of bugs fixed 🎉

[da5nsy]

From the original list we're now down to:

• \the-turing-way_main\book\website\communication\new-articles.md: WARNING: document isn't included in any toctree←[39;49;00m
• \the-turing-way_main\book\website\figures_figure-list.md: WARNING: document isn't included in any toctree←[39;49;00m
• \the-turing-way_main\book\website\project-design\sdp\pd-sdp-private-learning.md: WARNING: document isn't included in any toctree←[39;49;00m

(and of course some others have been introduced in the meantime 😭)

[bsipocz]

Oh, this is a great improvement! The remaining question then to whether they should be orphans, removed, or linked somewhere?

[da5nsy]

Oh, this is a great improvement! The remaining question then to whether they should be orphans, removed, or linked somewhere?

• delete (remove duplicate template file #2835)
• probably delete (Proposal: auto generate a Figure List #2834)
• link somewhere ([BUG] project-design\sdp\pd-sdp-private-learning.md isn't in the TOC #2833)

😅

[da5nsy]

OK.
The time has come.
I'm closing this issue.

🥳 😭 🎆 🍾

Hopefully, CI should now nip this kind of issue in the bud (since #2838 / #2861)

💤

[da5nsy]

Big thank you to @JimMadge who handled some of the gnarlier warnings on this list.

[JimMadge]

Great stuff @da5nsy @bsipocz 🎉

[aleesteele]

Well done, congrats folks!