search

SciML / Catalyst.jl

Chemical reaction network and systems biology interface for scientific machine learning (SciML). High performance, GPU-parallelized, and O(1) solvers in open source software.
https://docs.sciml.ai/Catalyst/stable/
Other
437 stars 71 forks source link

Update warn only #924

Closed TorkelE closed 3 weeks ago

TorkelE commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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