search

entangled / entangled.py

Python port of Entangled
Apache License 2.0
33 stars 7 forks source link

Integration with mkdocs example does not work out of the box! #38

Open stratosgear opened 9 months ago

stratosgear commented 9 months ago

I followed the example setup described in https://entangled.github.io/mkdocs-plugin/ and I was not getting what I was expecting.

For example, I added the very simple example defined in https://entangled.github.io/mkdocs-plugin/#annotate-code-blocks I was following, but the python source files were not generated. I thought it was a matter of restarting the mkdocs serve command but still no python file generated.

I had to open a separate terminal and run there: entangled watch to get the behavior I was expecting, meaning the creation of a example/hello_world.py file (although, following along the mkdocs init example, I would expect the file to be named: src/example_package/hello_world.py so that it would end up in the source folder already created from mkdocs, but I divert)

Isn't it the idea to trigger the entangled functionality through the mkdocs hook? Or maybe the instructions miss a step that explains that a separate process needs to run in parallel?

Not sure what is the intended usage here.

Nonetheless I'm thrilled if I can get this to work smoothly! :)

jhidding commented 9 months ago

Yes you're right. For some time I had entangled sync triggered by the mkdocs serve loop. This didn't always work as expected though. Entangled would not always be triggered when needed, leading to conflicts when both markdown and source code were changed. I had to disable the integration with the downside that you have to run entangled watch next to mkdocs serve.

In regard to the paths: Entangled takes all paths to be relative to the directory from which you run entangled.

stratosgear commented 9 months ago

I am not clear then on the use of the entangled plugin in mkdocs. Or is that obsolete too?

jhidding commented 9 months ago

It does transform the Markdown to render code blocks with a nice title. I do intend to extend support further (things like code navigation, figure captions) Just haven't found the time yet.

stratosgear commented 9 months ago

Ah yes, now I see it, thanks.

I'm not negatively critical here, I am just trying to figure out where things are given the state of the demos/documentation. I'm starting using it now, so maybe I'll have more feedback later on.

I'll leave the issue open, here, maybe as a reminder that the online instructions are out of date, maybe needing fixing?

jhidding commented 9 months ago

Yes, excellent!