Databind version

[rbroderi]

Relax databind version requirements.

[NiklasRosenstein]

Hey @rbroderi , could you explain what's blocking you with the current version requirements; or what feature of newer databind versions you want to use?

Unfortunately the next major versions of databind are not backwards compatible, meaning a bump of databind would require some refactor in Pydoc-Markdown as well as a major version bump in Pydoc-Markdown itself (given that its plugin system and config deserialization heavily relies on databind's deserialization behaviour).

I'm not saying I don't want to do this, I do, but I want to judge the priority of this since it's a bunch of work and I haven't been able to work on Pydoc-Markdown in the last few months and will likely not have much in the near future.

Cheers,

[ndejong]

Hi @NiklasRosenstein

+0.5 on this request.

The version misalignment with your slap-cli tooling (which is especially awesome) means that when trying to work with pydoc-markdown to auto-generate a changelog like this

@shell cd .. && slap changelog format --all --markdown

... means you land in an unhappy place with conflicts on the databind package like this

The conflict is caused by:
    slap-cli 1.7.6 depends on databind<3.0.0 and >=2.0.0
    pydoc-markdown 4.6.4 depends on databind<2.0.0 and >=1.5.0

The way I've been bitten with this today has been through trying to get everything working under readthedocs where I've not found a reasonable workaround - got as far as this and just gave up on the changelog in docs

[tool.readthedocs-custom-steps]
script = """
python -m venv slapcli
. slapcli/bin/activate
pip install slap-cli==1.7.6
deactivate
alias slap="VIRTUAL_ENV=${PWD}/slapcli ${PWD}/slapcli/bin/slap"
slap --version
cd docs
novella --base-url /
cd ..
cat docs/mkdocs.yml
python -m "$@"
"""

... the aliased slap does not carry through to the novella cmd-exec

Perspective then, this is currently rather inconvenient but not end-of-world - some documentation (probably in the novella project) that explains how to handle this type of situation probably goes a long way to mitigating the issue for the short term.

[ndejong]

This perhaps belongs on it's own thread/ticket but because it solves my above comment.

For the sake of future travelers passing this way because they are trying to solve getting novella and pydoc-markdown to work with readthedocs.io

.readthedocs.yml

version: 2
mkdocs:
  configuration: "docs/mkdocs.yml"
build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
python:
  install:
    - requirements: docs/requirements.txt

docs/requirements.txt

readthedocs-custom-steps==0.6.2
mkdocs-material==9.1.9
pydoc-markdown==4.6.4
novella==0.2.5

pyproject.toml

[tool.readthedocs-custom-steps]
script = """
cd docs
novella --base-url /en/latest/
mkdir -p ../_readthedocs
mv _site ../_readthedocs/html
echo "COMMAND-PREVENTED: $@"
"""

[NiklasRosenstein]

Pydoc-Markodwn 4.8.0 now uses Databind ^4.3.0. The semantics of Databind v4 are sufficiently similar to v1 for Pydoc-Markdown to not require a major version bump after all, although some users that use it's API and thus also may have used some features of Databind v1 may need to update their code alongside a bump with their own declared Databind dependency.

@ndejong I think you were on the right track to work around the incompatibilities. In the future this might happen again as there's no guarantee that the dependencies of the different tools will stay compatible. (That's one of the reasons why tools like Pipx exist). Having the slap CLI permeate into the novella process' environment could be fixed by explicitly setting PATH or linking slap to a location that's already on the PATH.