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

[docs] add DocumenterCitations #3596

Merged
merged 10 commits into from
Dec 8, 2023
Merged

[docs] add DocumenterCitations #3596

merged 10 commits into from
Dec 8, 2023

Conversation

blegat
Copy link
Member

@blegat blegat commented Dec 6, 2023

I always found it quite difficult and time consuming to manage citations and ensure a uniform look. Just found this DocumenterCitations which seems promising so let's see how it looks. I started with just a few citations as a proof of concept.

Preview https://jump-dev.github.io/JuMP.jl/previews/PR3596

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
Copy link

codecov bot commented Dec 6, 2023

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (419c334) 98.39% compared to head (d8ddc4b) 98.29%.
Report is 2 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #3596      +/-   ##
==========================================
- Coverage   98.39%   98.29%   -0.11%     
==========================================
  Files          38       38              
  Lines        5687     5686       -1     
==========================================
- Hits         5596     5589       -7     
- Misses         91       97       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@odow
Copy link
Member

odow commented Dec 6, 2023

cc @goerz any ideas about this?

image

@goerz
Copy link
Contributor

goerz commented Dec 6, 2023

I have a vague memory of having seen something like that before… I think it might have been if you forget to have a (canonical) bibliography block? That is, there’s nothing for the reference to link to?

Are you using the latest version? Because I also recall doing something do give a clear error message in such a situation (or maybe it was just something I wanted to do and then forgot to follow up on)

docs/src/index.md Outdated Show resolved Hide resolved
@odow
Copy link
Member

odow commented Dec 6, 2023

Are you using the latest version?

Yip. We're using

Installed DocumenterCitations ────────── v1.3.2

@goerz
Copy link
Contributor

goerz commented Dec 6, 2023

Hard to say… I tried to reproduce it locally after checking out that PR branch, with

julia --project=docs
(docs) pkg> dev .
(docs) pkg> instantiate
julia> include("docs/make.jl")

but that never gets to the error with the bibliography, as it fails with during the doctests/tutorials with

...
Terminated with status = numerical error
solve time =  165ms
/Users/goerz/Documents/Programming/JuMP.jl/docs/src/tutorials/applications/optimal_power_flow.jl: Test Failed at /Users/goerz/Documents/Programming/JuMP.jl/docs/src/tutorials/applications/optimal_power_flow.jl:420

Do you have any special instructions for building the documentation? I was trying this on my MacBook; should I use my Linux workstation instead?

(I'd maybe recommend creating a Makefile so that make docs, make tests, etc. works)

If I can reproduce it, I'll see if I can figure out what's going on with the citation.

@odow
Copy link
Member

odow commented Dec 6, 2023

It's not uncommon for that doctest to fail on Mac. But things pass on CI so I haven't spent too much time looking into it.

I'd just delete the OPF line from

"tutorials/applications/optimal_power_flow.md",

as well as the file itself.

@goerz
Copy link
Contributor

goerz commented Dec 6, 2023

I was still having trouble on my MacBook, so I just switched to Linux. Took a while to run through the build, but it finished now, and I'm not seeing any errors:

CleanShot 2023-12-06 at 17 23 54@2x

Everything seems fine when I look at the rendered HTML, too. Both the citations and the bibliography are there.

As a matter of style, I would probably recommend putting the Bibliography on a separate page at the end of the documentation (especially if the list of references grows large), but that's up to you.

@odow
Copy link
Member

odow commented Dec 6, 2023

What if you run with ENV["CI"] = "true" to that it runs with prettyurls

prettyurls = get(ENV, "CI", nothing) == "true",

As a matter of style, I would probably recommend putting the Bibliography on a separate page at the end of the documentation

Yeah will do. @blegat was just trying this as a proof of concept.

@goerz
Copy link
Contributor

goerz commented Dec 6, 2023

Sure, I'll try the CI=true. If it fails in some weird way, I'd also recommend temporarily activating the DEBUG logging in the workflow: https://juliadocs.org/DocumenterCitations.jl/stable/internals/#Debugging

edit: still working fine

@odow
Copy link
Member

odow commented Dec 6, 2023

For some reason 50c3859 fixed it...

@odow odow changed the title [POC] BibTeX -> cite with DocumenterCitations [docs] add DocumenterCitations Dec 6, 2023
docs/make.jl Outdated Show resolved Hide resolved
docs/make.jl Outdated Show resolved Hide resolved
@blegat
Copy link
Member Author

blegat commented Dec 7, 2023

For some reason 50c3859 fixed it...

😮 I guess it's because we shouldn't use the same plugin instance for the pdf and the html, good catch

@blegat
Copy link
Member Author

blegat commented Dec 7, 2023

Just tried one with an accent with Matousek2013. I assume that for the LaTeX -> pdf build to work, we should escape the accent so I used {\v{s}} and it's working in the HTML build as well so it seems to be the way to go unless the LaTeX build works without the escaping

Copy link
Member

@odow odow left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Can fix the various other references over time.

@goerz
Copy link
Contributor

goerz commented Dec 7, 2023

Just tried one with an accent with Matousek2013. I assume that for the LaTeX -> pdf build to work, we should escape the accent so I used {\v{s}}

The escaped version is fully supported, but Unicode should work as well, both for HTML and TeX/PDFs. I’ve been using unicode in my .bib files for years, and haven’t had any problems. Officially, bibtex is still “ascii-only”, so I don’t know why it works, but any installation of LaTeX on Linux and macOS I’ve used since at least 2015 just does the right thing.

@blegat
Copy link
Member Author

blegat commented Dec 8, 2023

@goerz Thanks! I guess both can be used then

@blegat blegat merged commit 60dc624 into master Dec 8, 2023
11 of 12 checks passed
@blegat blegat deleted the bl/doc_cite branch December 8, 2023 10:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants