Revert "docutils: 0.19 → 0.20.1"

[AndersonTorres]

Reverts #243078

Unfortunately

• Sphinx 5.3.0 does not support docutils >= 0.20;
• Sphinx 7.1.2 (the most recent) needs some heavy patching;

[tjni]

We will get this done again soon (I hope)!

[toastal]

Might it make more sense to have a docutils-0_19 version for legacy purposes if Sphinx is problem? There are a couple of OCaml packages like this I know. I’m still against reverting progress just because an outdated downstream dependency isn’t taken care of.

I’m currently already using features from the latest version.

[tjni]

This isn't common practice in our Python packaging because only one version of a dependency can be on PYTHONPATH. (Does OCaml have the same problem?) We do sometimes override versions in consuming applications, however. How are you consuming the latest version, maybe there's a way to accommodate it without changing the common practice.

[toastal]

https://github.com/NixOS/nixpkgs/tree/1daf1298306546c39b3ed0e336a63a02339d4d0a/pkgs/development/ocaml-modules/mtime

mtime is one of those packages I had to deal with recently when getting an OCaml library merged. mtime stays at latest stable. Legacy applications & libraries using an old, unsupported version now use a pinned old version @ mtime_1. According to this (

nixpkgs/doc/languages-frameworks/ocaml.section.md

Line 29 in caac0eb

OCaml libraries should be installed in `$(out)/lib/ocaml/${ocaml.version}/site-lib/`. Such directories are automatically added to the `$OCAMLPATH` environment variable when building another package that depends on them or when opening a `nix-shell`.

), libraries as buildInputs get added to the OCAMLPATH env var.

With applications they are used as a separate buildInput

nixpkgs/pkgs/applications/science/logic/acgtk/default.nix

Line 21 in 1daf129

ansiterminal cairo2 cmdliner fmt logs menhirLib mtime_1 sedlex yojson

With libraries, it’s overridden on callPackage

nixpkgs/pkgs/top-level/ocaml-packages.nix

Line 57 in 1daf129

awa = callPackage ../development/ocaml-modules/awa { mtime = mtime_1; };

[tjni]

How does OCaml handle the situation when two versions of the same library are asked for in OCAMLPATH?

[toastal]

Not entirely sure how that scoping or version picking is done.

[tjni]

Got it, that's the main reason why we currently require only a single version of every library in the package set. I'm sure you can find exceptions that have been justified, and applications can override any library they need to, as nothing depends on them.

How are you pulling in the latest version of docutils and using it?

[toastal]

How are you pulling in the latest version of docutils and using it?

From staging as a self-made overlay. Could I still use an overlay, yes? But we would be stepping backwards to from a stable version to one that isn’t supported.

[tjni]

But we would be stepping backwards to from a stable version to one that isn’t supported.

I'm very sorry about this, but the only two ways forward I see are either reverting this or updating sphinx. Used as a library, we need to choose one version of docutils, and we cannot break sphinx; it's at least part of the darwin stdenv bootstrap (it's needed to build LLVM's manpages).

I haven't looked into all of the options for fixing sphinx (except that updating it is not trivial). However, if we can resolve that we should be able to try updating docutils again.

[tjni]

I'll think a little more about if #244625 is the best approach to updating sphinx and try to get it across the finish line soon.

[AndersonTorres]

Might it make more sense to have a docutils-0_19 version for legacy purposes if Sphinx is problem?

1. My intention was to update docutils and sphinx in lockstep;
2. I would like this idea until I have read all the conversation above :/

[toastal]

But Docutils is a standalone tool?

[tjni]

Oh, I see, it's both an application and a library, and you're using the application part. Then it would be possible to update only the application. It's currently defined as:

docutils = with python3Packages; toPythonApplication docutils;

so it's possible to stop reusing the docutils library and write a separate derivation for the application.

[tjni]

#249518 would do that if it's wanted

[AndersonTorres]

It is a standalone tool and a library.
And, as said above, it is a dependency of many important things.

[AndersonTorres]

@tjni should I close this?

[tjni]

I think we still need this, it downgrades the library while #249518 updates the application again.