Cycling to rebuild docs, now that upstream has been updated

Cleaned this one up, thanks!

The build is broken because of#28820, but fixing that, it'sreally broken becauseinternal: too-much is not a valid tag.

internal: too-much is not a valid tag.

how come? (Last I checked, we don't do any validation on tags)

I'd prefer that we don't use the tagging mechanism for internal suff. Making internal labels public is confusing, OTOH packing them behind.. ifconfig is extra effort (and doesn't work if you want to have public tags at the same time).

It would work, ifsphinx-tags had a configuration to exclude certain tags. But that does not exist right now.

and doesn't work if you want to have public tags at the same time

That should if you put it behind a new tag directive

Well, I feel uncomfortable, with this duct-tape coding of internal tags via.. ifconfig. It's cluttered and difficult to write for tag authors. But it technically, works and could be refactored later. So I won't block, but please find somebody else to approve.

It's cluttered and difficult to write for tag authors.

I agree, I just don't want to lose this information b/c right now I don't have the bandwidth to figure out how to get it working on the sphinx-tag side.

So I won't block, but please find somebody else to approve.

Thanks for the heads up.

Problems with examples should be issues for discussion, not tags.

Problems with examples should be issues for discussion, not tags.

Why not both? The idea here is use tags to get a holistic overview and also flag those examples in the dev version. I think that makes it easier to then write an issue, especially if the fix is more holistic.

Because tags are for users to find things in the docs. Issues are for maintainers to track issues.

Basically by tagging an example as "too much" you are issuing a judgement. To remove your judgement I would then have to open a PR to change the tag. That is backwards to how an issue works, where there are no committed changes until a PR is approved.

Is it sufficient to create a collection issue for "example rework"? Instead of adding ainternal: needs review tag to the code, add a line in the issue

• internal: needs review:https://matplotlib.org/devdocs/gallery/statistics/errorbar.html

This is much more lightweight. It can be edited without a PR and review. Also it's possible to add a few words for context to the point. The tag must stand for itself.

The only downside I see is that non-core devs likely don't have the right to edit that issue. But that's not too bad. They can comment on it and we merge the comments in to one top-level list if needed.

Because tags are for users to find things in the docs.

These are tags that only show up in the dev version, which we generally don't want users using

To remove your judgement I would then have to open a PR to change the tag.

Or request changes on the PR and have a discussion there?

The only downside I see is that non-core devs likely don't have the right to edit that issue.

That's sorta what motivated having the internal tags in the first place - to give contributors and maintainers a quick way to flag examples that need to be looked at, and using the tags machinery to get a quick list with links of those examples.

The issue version ends up being a top down scan all the examples, while the tag version is "oh, looking through this example for other reasons, it also should get added to the list for review".

For me a compromise would maybe be a pinned issue or template for unclear examples w/ tagging - something where the tracking issue isn't getting buried on page 3.

I'll stand by my stance documentation tags should not be used to organize issues. There arelots of mechanisms to organize and surface issues on GitHub, specifically tags and projects, and we should use those.

removed the internal tags so this can get merged