[Doc]: create sphinx configuration that skips on dependencies

[story645]

Documentation Link

https://matplotlib.org/devdocs/devel/documenting_mpl.html#building-the-docs

Problem

Latex, graphviz, and inkscape are kind of heavy dependencies to install if you're working on documentation changes that don't depend on latex, graphviz, or inkscape - like most of the gallary and a lot of the tutorials.

Suggested improvement

Can we adopt a sphinx equivalent of skipif? Two ways of doing this are: (edit: these are both sphinx directives)

	..ifconfig	..only
pro	arbitrary conditions as part of the directive	have to explicitly enable with -t flag
con	unclear how to disable	have to maintain list of tags/conditions

[timhoffm]

I have mixed feelings on this. On the one hand, not having to install those can be convenient. On the other hand, we introduce additional complexity into our logic and results depend on what you have installed, which can also be confusing.

[story645]

Yeah so that's why my bias is that we do this as an explicit 'sphinx no-external-deps` type build option, it would just maybe be slightly more work. The upside is it makes the 'setting up matplotlib' process much faster for the folks who aren't touching the examples that need latex/graphvix, and inkscape-> which honestly separately it might be useful to have an inventory of those examples.

[timhoffm]

If somebody is interested in this, I think the only way forward is trying out and seeing how complex it gets.

[story645]

Yeah...I'm a little worried about the scope of work w/o a definite 'yes, we want this' but that can maybe be limited by starting out w/ one dependency and one example as a draft?

[timhoffm]

We have the following note

The documentation will not build without LaTeX and Graphviz. These are not Python packages and must be installed separately. The documentation can be built without Inkscape and optipng, but the build process will raise various warnings. If the build process warns that you are missing fonts, make sure your LaTeX distribution bundles cm-super or install it separately.

Maybe worry about Inkscape last, because that's already optional.

The approaches of handling LaTeX vs Graphviz are probably very different:

• AFAIK Graphviz is only used for inheritance diagrams. They are directly built into the API docs, so you need either live-patch the respective .rst files (:fearful:) or get a PR into sphinx that allows ignoring inheritance diagrams via a config parameter.
• I'm not sure how to approach Latex. You could try and skip the examples/tutorials that use it, but it may well be that we have plots with LaTeX in the changelog or FAQ.

Overall, I'm afraid either of these is quite some work and I wouldn't spend time on that. That said, I would accept such a PR as long as it does not add much complexity on our side.

---

Edit / Note: the Graphviz part can likely be solved using .. only:: directives around the inheritance diagram, see https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags, e.g.

.. only:: show_inheritance_diagram

   .. inheritance-diagram:: matplotlib.ticker
      :parts: 1

[story645]

Note: the Graphviz part can likely be solved using .. only:: directives around the inheritance diagram

Or the ifconfig directive, but there are trade offs on flexibility and configuration. Like I'm pretty sure we can isolate using directives, I'm more unsure which one.

Maybe just experiment w both, but I opened this issue largely to pin down what are the requirements on the build - does this have to be off by default, are there external dependencies that are non-negotiable, etc.

[tacaswell]

I am very skeptical of this idea and basically agree with @timhoffm .

Guarding the inheritance diagrams with a .. only or .. ifconfig is reasonable but one more thing to remember to add if/when we add more. However, as Tim says this is currently all speculation and it is impossible to decide until we see what the complexity actually is.

---

I think the time spent on this would be better spent getting something like gitpod working or reviving the container work. That also brings in another complex technology (docker/podman), but it is a tech stack many people already have installed there is broadly available expertise in.

[story645]

Guarding the inheritance diagrams with a .. only or .. ifconfig is reasonable but one more thing to remember to add if/when we add more

We already do this w/ tests - ifconfig/only are analogs for skipif, so why is this more of a burden for docs?

[timhoffm]

Guarding the inheritance diagrams with a .. only or .. ifconfig is reasonable but one more thing to remember to add if/when we add more

We already do this w/ tests - ifconfig/only are analogs for skipif, so why is this more of a burden for docs?

I think the overhead is bearable because we rarely add modules. The worst that can happen is that we forget it. Then, a user is not worse off than now. Ideally, they report it back and we fix it. Since it only affects dev, fixes take effect immediately.

[story645]

I think the overhead is bearable because we rarely add modules.

I think we also rarely add new inheritance diagrams, or examples that rely on a full latex build or SVG.

What prompted this issue was how long it was taking a participant at pydata NYC sprints to install everything on their machine for a documentation PR that didn't need any of that.

I'm 100% on board w/ docker/gitpod/code spaces & I'd also like to have a low bandwidth/low space on hard drive alternative. Also think specific flagging could be useful for better iding requirements #23831

[tacaswell]

@story645 Please go ahead and add all the skipifs + make target so we can see what it looks like.

I do not think there is more to say here until we have some hard information about what this actually looks like.