feat(plot_directive): add RST directory option #26099
Conversation
Hello! After trying to set up my own documentation, I had trouble making the `plot_directive` work with the `autodoc2` extension. `autodoc2` is unlike `sphinx.ext.autodoc` because it automatically generates all RST files, at a place that is not the same where we would usually call `autodoc`'s directives. To cope with this problem, I had to implement my own Sphinx directive, based on yours. This may not be the perfect solution, but it works fine. Feel free to suggest any change :-) If you want to see a live example of this, here is the repo I developed the solution for: https://github.com/jeertmans/DiffeRT2d
There was a problem hiding this comment.
Thank you for opening your first PR into Matplotlib!
If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks.
You can also join us on gitter for real-time discussion.
For details on testing, writing docs, and our review process, please see the developer guide
We strive to be a welcoming and open project. Please follow our Code of Conduct.
|
Trying to understand this, it looks like the local variable matplotlib/lib/matplotlib/sphinxext/plot_directive.py Lines 916 to 926 in 3b30f47 build_dir=build_dir_link. Given that, I think that if we do take this the name should be something like plot_build_directory to be clearer about what it is actually affecting (rst_dir makes sense in the code as it is extracted from the path to the rst file).
I am also a little confused by why this is needed. Is We are trying to infer the build directory, is there a better way to get that directly? |
Co-authored-by: Thomas A Caswell <tcaswell@gmail.com>
Co-authored-by: Thomas A Caswell <tcaswell@gmail.com>
Well this is not the build dir neither. Because the build directory is another place, but that also depends on the filename… For example, the build dir’s default location with my setup is put inside the docs/source dir, not the docs/build dir, which seems weird to me too.
Autodoc2 generates source files, but is hardly configurable. So a solution could be to modify their extension by adding more flexibility, or adding some kind of post processor. To me, the easiest solution was just to add a new configuration variable to the matplotlib extension. In my opinion, but the matplotlib extension and the autodoc2 extension could be a bit more configurable :)
Maybe, I tried to read a bit the code but it is quite hard to determine the implication of each variable :’-) |
|
|
||
| .. code:: python | ||
|
|
||
| plot_rst_directory = "source/apidocs/<your_package>/" |
There was a problem hiding this comment.
Is there a way we can explain the folder situation here? Is this guaranteed to be always under the API docs source dir? I'm thinking of a potential mix between api and narrative docs and where the plots would live for this intermediate state.
|
I have a memory of leaving another comment here but apparently not 😞 How does this interact with #24205 and is this related to the issue discussed in I am still very skeptical of this as-is. I think the analysis we need is a flow diagram of how the whole sphinx build process works here (I think we generate rst + images that get put in the source in an early step and then a late step goes discovers them and then generates the html which is why the "builddir" of this step is the "sourcedir" of the next step). There is clearly something wrong with the logic to generate the various paths (and the internal variable names could be improved), but adding a global setting to reach in and override a particular bit of the logic is unlikely to be the best solution. Even if we do have to do something like that, I remain skeptical that this is is the right place to put the knob. |
|
I was just working on the directive so I will take a look in the next day or so. |
|
What happens is explained at https://github.com/matplotlib/matplotlib/blame/67c4bb3986e3bccfcebc69d1177007d4aa4483d2/lib/matplotlib/sphinxext/plot_directive.py#L154. I was going to say it is well-explained, but I wrote it, so I guess I think just like the author. If we have an rst file in For our API data, it generates rst files under I don't understand why the current PR wants to change |
Co-authored-by: Melissa Weber Mendonça <melissawm@gmail.com>
|
If think the issue here is that |
|
I've moved to draft, but feel free to put back in the queue if you think this is ready,. |
|
Hi @jklymak, I am marking as ready as I have finally found some time to create a MWE: https://github.com/jeertmans/matplotlib-mwe-26099. GitHub actions are automatically run, and the latest ones show that apply the fix is necessary to build the documentation correctly. See build logs when the fix is not applied: |
Hello!
PR summary
After trying to set up my own documentation, I had trouble making the
plot_directivework with theautodoc2extension.autodoc2is unlikesphinx.ext.autodocbecause it automatically generates all RST files, at a place that is not the same where we would usually callautodoc's directives.To cope with this problem, I had to implement my own Sphinx directive, based on yours.
This may not be the perfect solution, but it works fine.
Feel free to suggest any change :-)
If you want to see a live example of this, here is the repo I developed the solution for: https://github.com/jeertmans/DiffeRT2d.This example plot is available here: http://eertmans.be/DiffeRT2d/apidocs/differt2d/differt2d.scene.html#differt2d.scene.Scene.basic_scene.EDIT: documentation examples are no longer online, but you may see the repository at the specific version the error was found.
PR checklist