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

Update warn only #924

Closed
wants to merge 1 commit into from
Closed

Update warn only #924

wants to merge 1 commit into from

Conversation

TorkelE
Copy link
Member

@TorkelE TorkelE commented Jun 8, 2024

Sorry @isaacsas I messed up when we updated this one. I think the warnonly lists the warning types that does not generate errors and instead only warnings (with warnonly = true being equivalent to listing all).

This update should prevent doc build errors from missing cross_references and footnotes that occur as an entry only.

For the missing cross_references I plan to make an update today/tomorrow which removes all [text](@ref ref) entries. They are meant to mark places where we should put an entry when the doc they reference is added (e.g. Jump performance). However, having a PR which just removes them from the text should be enough, later on, I can just check that one where there were changes and add them back in.

The footnote thing we use in a few places where there are general references that does not directly fit in, e.g.
image
In the intro to Catalyst for new Julia users doc, so I think that one should probably stay.

@isaacsas
Copy link
Member

isaacsas commented Jun 8, 2024

The update to missing_docs was because that was the current SciML standard I thought. But I am fine copying what MTK does, see

https://github.com/SciML/ModelingToolkit.jl/blob/3b340c2e392e9908a06f768eb69ebaf292b12ed9/docs/make.jl#L26

I don’t understand the need for excluding footnotes though; does that mean we are using them incorrectly?

@TorkelE
Copy link
Member Author

TorkelE commented Jun 8, 2024

What MTK does look odd? maybe we should ask about it.

If there is another way to get formated reference entries at the bottom of a page without

[^1]: [Jeff Bezanson, Alan Edelman, Stefan Karpinski, Viral B. Shah, *Julia: A Fresh Approach to Numerical Computing*, SIAM Review (2017).](https://epubs.siam.org/doi/abs/10.1137/141000671)

I am all for it, but not certain. What we do not do is then put a [^1] in the next to give a marker for it. If you want we could change e.g. to

The Catalyst tool for the modelling of chemical reaction networks is based in the Julia programming language [^1][^2]`.

though. It felt a bit unnatural when I wrote it though.

@isaacsas
Copy link
Member

isaacsas commented Jun 8, 2024

It isn’t a big deal either way, but I’d keep the missing doc warning not causing failures. As I said that was standard for all of SciML when updating to V1 of Documenter.

@TorkelE
Copy link
Member Author

TorkelE commented Jun 8, 2024

Good point about the SciML standardization. Agreed that this is not big enough to break with it.

@TorkelE TorkelE closed this Jun 8, 2024
@TorkelE TorkelE deleted the update_doc_warnonly branch June 8, 2024 18:22
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.

None yet

2 participants