Too long texts in ReadTheDocs

[matthias-ronge]

Our menu texts are too long, so the control line breaks into two lines and covers the upper part of the help page:

With short texts, it looks right:

[Erikmitk]

My preferred solution would be to change/adjust the theme. https://www.mkdocs.org/user-guide/styling-your-docs/

[Erikmitk]

Actually… it looks like the ReadTheDocs (RTD) infrastructure is at fault. The long values aren't even supposed to be there. README has no place in the navigation. Something fishy in the build process is going on.

My fork builds cleanly in RTD. The difference is that I have the Python Interpreter for building set to 3.x. When I try to change the official documentation to the same settings it fails to build. I suspect an outdated mkdocs dependency due to the error message. I tried wiping the build environment but that didn't change a thing. 😞

[Erikmitk]

https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html

We strongly recommend to pin the MkDocs version used for your project to build the docs to avoid potential future incompatibilities.

We might have to add a configuration.

(Although it's super weird that my fork builds the documentation clean out of the box.)

[bertsky]

My fork builds cleanly in RTD.

@Erikmitk, what do you mean by that? Do you have a readthedocs.io deployment for your fork (where?), or is it just your local mkdocs serve -t readthedocs (or just mkdocs serve) that looks correct?

IMO the issue here is actually much broader: currently, in the RTD deployment, none of the images in the user documentation resolve correctly. I attempted #5221 to solve that (by prefixing all references with /docs), only to find out the image paths were correct, but the deployment was not.

So this is quite urgent, actually. (Also, running mkdocs should be documented and probably put into the CI...)

[Erikmitk]

@bertsky This is quite an old issue but I just checked if it still persists. I have access to two projects on RTD:

Both can be built but this official .Production repo renders a broken documentation.

My identical fork renders a readable version.

I gave up on this in November 2020 because it seemed like an issue on the RTD platform itself where the build process was somehow glitchy. That's when I added the comment about adding a RTD config to the project. There were no differences in the settings in both projects on RTD and the source code is identical. Even locally mkdocs serve -t readthedocs worked for me as well. I still have no idea why this happens.

[bertsky]

My identical fork renders a readable version.

Interesting. However, did you notice that even in your deployment, within the user section, none of the images resolve correctly? (They come with absolute links like /user/pictures/ProduktionsvorlageLaufzettelAuswaehlen.png, lacking either /en/master or ../../.. as a prefix.)

In a local deployment (with latest mkdocs==1.3.0 for Python 3.7), these image links are all correct.

I just registered with RTD myself and set up a build for my GH fork of Production (setting master / mkdocs / English / Java). I ran into this build error. To me this seems to be caused by readthedocs.org configuring mkdocs<1.1. The default config does set CPython 3.X, so at least your concern regarding Python 2 vs 3 seems to be gone. It offers selecting a requirements.txt or conf.py from the repo, which obviously (this being a Java project) we don't have. So something within RTD drags in that bogus mkdocs<1.1 requirement...

(Unfortunately, the RTD docs on Github integration does not have to say anything about mkdocs. And on the Github side, Settings → Webhooks → RTD, I cannot configure anything related to the generator at all.)

[bertsky]

To me this seems to be caused by readthedocs.org configuring mkdocs<1.1. The default config does set CPython 3.X, so at least your concern regarding Python 2 vs 3 seems to be gone

Ha! It does in fact revolve around that problem, though: Comparing my build log to your build log, one immediately notices:

• yours: Python 2.7, installs ... mkdocs
• mine: Python 3.7, installs ... mkdocs<1.1

So you were right above.

I believe this existing issue explains the RTD side. IIUC, all we have to do is amend our existing mkdocs.yml with a statement on the mkdocs version.

[bertsky]

Spoiler: I did add a docs/requirements.txt, and it does repair the Python 3 build of RTD.

But the images are still broken.

So the culprit must be within the difference between locally running mkdocs and having RTD do it.

[Erikmitk]

However, did you notice that even in your deployment, within the user section, none of the images resolve correctly?

HA! Yesterday I checked this architecture section and all the images work perfectly fine!!

It looks like this is broken at the source since the images in the user section don't even work for me here in the repo:

User section: ❌ https://github.com/kitodo/kitodo-production/blob/master/docs/user/introduction/index.md
Architecture: ✅ https://github.com/kitodo/kitodo-production/blob/master/docs/developer/architecture/README.md

So the images (paths, I guess) in the repo need to be fixed and a requirements.txt for the docs to get the same repeatable build process.

[bertsky]

Yesterday I checked this architecture section and all the images work perfectly fine!!

Yes, but in that section the images are actually either remote references or just filenames (i.e. relative to the Md directory).

It looks like this is broken at the source since the images in the user section don't even work for me here in the repo:

Yes, in the user section, all images are in /docs/users/pictures/..., but the references use /users/pictures/... for some reason.

So the images (paths, I guess) in the repo need to be fixed and a requirements.txt for the docs to get the same repeatable build process.

In #5221 I tried with additional /docs prefix, and that works on the Github website, but neither the locally or the RTD deployed mkdocs will work with these paths. (I did not try with ../../.. though.)

I believe there must be some setting (that likely has changed in recent mkdocs versions) for the reference of absolute links. So IMO we should fix the configuration, not the Markdown files.

[bertsky]

@Erikmitk see #5225.

Perhaps we should also set up GH actions on the upstream repo.

[matthiaskissler]

This issue can be closed, the content was moved to the Wiki section in Github: https://github.com/kitodo/kitodo-production/wiki/Developer-Documentation-Kitodo.Production-3.x