Closed rbroderi closed 1 year ago
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,
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.
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: $@"
"""
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
.
Relax databind version requirements.