search

sphinx-contrib / aafig

Sphinx extension to add ASCII-art diagrams using aafigure
https://pypi.org/project/sphinxcontrib-aafig/
Other
1 stars 9 forks source link

Is sphinxcontrib.aafig parallel read safe? #12

Open r-pufky opened 3 years ago

r-pufky commented 3 years ago

I started to do doc building in parallel using -j auto, and aafig raises the following warnings:

WARNING: the sphinxcontrib.aafig extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit
WARNING: doing serial read

The relevant sphinx extension documentation is here: https://www.sphinx-doc.org/en/1.5.1/extdev/#extension-metadata

Essentially you can declare aafig safe for parallel reading by adding this to setup():

parallel_read_safe=True

The question is if aafig is parallel read safe? If it is, I can submit a CR to get this added to the setup.

llucax commented 3 years ago

I'm quite distanced from both Sphinx and aafig so I don't know what being "safe for parallel reading" means. Do you have any links explaining that?

r-pufky commented 3 years ago

No worries - see attached link above. Highlights are:

parallel_read_safe: a boolean that specifies if parallel reading of source files can be used when the extension is loaded. It defaults to False, i.e. you have to explicitly specify your extension to be parallel-read-safe after checking that it is.

llucax commented 3 years ago

Thanks, I read the link but I still don't get very well the specifics, but as I said it's been long while since the last time I used Sphinx.

I guess it should be parallel_read_safe because in theory there shouldn't be any reason not to, but also aafigure is an oldish library (last release was 4 years ago), and I'm not sure if it might be doing stuff that might not be parallel_read_safe (using global variables is? I still don't know if aafigure does, I'm just thinking about possible scenarios).

I don't have the time to go through Sphinx code + aafigure code to make sure this works, so I'll leave it open and indicate someone should pick it up. If it helps, I'm glad to make a PR myself if someone is willing to test it.

r-pufky commented 3 years ago

I can take a crack at it.

On Mon, Feb 15, 2021, 09:35 Leandro Lucarella notifications@github.com wrote:

Thanks, I read the link but I still don't get very well the specifics, but as I said it's been long while since the last time I used Sphinx.

I guess it should be parallel_read_safe because in theory there shouldn't be any reason not to, but also aafigure is an oldish library (last release was 4 years ago), and I'm not sure if it might be doing stuff that might not be parallel_read_safe (using global variables is? I still don't know if aafigure does, I'm just thinking about possible scenarios).

I don't have the time to go through Sphinx code + aafigure code to make sure this works, so I'll leave it open and indicate someone should pick it up. If it helps, I'm glad to make a PR myself if someone is willing to test it.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/sphinx-contrib/aafig/issues/12#issuecomment-779365773, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABEOQPQ2XBNLZZOGTFALULLS7FLMNANCNFSM4XQFIQJQ .