Move Tidelift content out of the sidebar

[jaraco]

Except as part of Table of Contents and borrow For Enterprise content from urllib3. Ref pypa/setuptools#2465.

[jaraco]

This isn't working as intended. When merged with Setuptools, the name 'project' appears literally. I need to find some way for the project name to render from the config.

[jaraco]

@pradyunsg: I'll need to figure out how to substitute the project variable for those {{ project }} blocks. Do you know how to do that?

[jaraco]

I did find I could use this technique to perform the substitutions in text, but that doesn't work for the URLs. It looks like it might take some more magic to be able to generate the necessary URLs. It may be the case that a specialize Sphinx plugin might be necessary. If that turns out to be the case, perhaps jaraco.tidelift would be a good place to implement that plugin.

[webknjaz]

By the way, for |project| to work, you need to declare it as a substitution via rst_epilog.

[jaraco]

By the way, for |project| to work, you need to declare it as a substitution via rst_epilog.

Now with jaraco.packaging 8.2, the |project| substitution gets created in an epilog in the plugin.

[jaraco]

I wish I understood the relationship between templates and docs. I'd sure like to implement the For Enterprise block as an HTML template and include it in the rst doc.

[pradyunsg]

I'm gonna be AFK from Github until New Year's as a "let's not go overboard" exercise.

This is pretty high up in my "take a look at to move this forward" list. I'm still not a 100% sure how exactly this project is related to the setuptools documentation, or if it only serves as "the reference that's copy-pasted around" or something else entirely.

[webknjaz]

I wish I understood the relationship between templates and docs. I'd sure like to implement the For Enterprise block as an HTML template and include it in the rst doc.

You can't inject HTML into RST w/o a non-native directive. Sphinx has the concept of templates that are jinja2-based. Their paths get registered via a normal sphinx ext mechanism (the setup() hook). Each theme has an ini config that is exposed to jinja2 templates and can be extended/redefined via certain vars in conf.py. But that's about it. Templates know nothing about RST (in fact, the source can be MD or something else and jinja2 doesn't care about that). Sphinx collects and renderes the documents and then passes the resulting HTML into the templates, and I think it also injects ToC into the context in a similar manner. So RST/MD is completely decoupled from j2. The only way to inject j2 into RST is to have a third-party extension that would evaluate those templates separately from the regular templating in the builders. This is why many extensions resort to using client-side JS instead, to add various blocks/panels that should appear in the document area. You could probably bypass RST and use pure HTML on some URLs but that would be rather disconnected from the sphinx machinery. There's also a way to extend the theme template with j2 but it's theme-specific: you basically create files with the same name as ones in the theme and j2 will pick those up instead. Some themes even have dedicated empty blocks that you'd redefine when inheriting templates to make things appear in some places, like footer.

Here's another thought: I prefer having that Tidelift block right in the README.rst that gets rendered on GitHub and PyPI meaning that there's no way to use the dynamic templating but the upside is that you can seamlessly include that readme or a part of it into the index page in sphinx. Although, if you'd want to use some templating, there could be some external mechanism to generate the static readme and commit it.

[webknjaz]

I'm still not a 100% sure how exactly this project is related to the setuptools documentation, or if it only serves as "the reference that's copy-pasted around" or something else entirely.

Jason leverages the power of Git subtrees to merge a set of config and project layout files into different repos he maintains. And some of those configs point to plugins for different tools (pytest/sphinx/etc) that encapsulate even more shared configuration that often gets activated dynamically (which is rather implicit and unobvious but there's a skeleton.md file in the repos explaining how this is maintained).

[jaraco]

I'm still not a 100% sure how exactly this project is related to the setuptools documentation, or if it only serves as "the reference that's copy-pasted around" or something else entirely.

Jason leverages the power of Git subtrees...

That's mostly correct, though I don't use Git subtrees. I merely separate the concerns into separate, supporting repos. So jaraco/skeleton is the project skeleton (package metadata, testing infrastructure, ...). jaraco/tidelift is similar, but augments projects based on jaraco/skeleton to implement the content for Tidelift-sponsored projects.

Unlike git subtrees, which creates a separate subdirectory for the content, these repos are merged into the target projects (so common techniques in pyproject.toml or setup.cfg or pytest.ini are stored in the exact same commit), so that as the adopting project evolves, the changes from the skeleton repos can continue to be applied, and the conflicts resolve. The most important feature here is that nothing is copy-pasted around. The code and packaging metadata and tidelift sponsorship concerns evolve independently, but the improvements to the supporting repos can be applied to all of the projects that adopt them. Of course conflicts arise, but the git tooling helps reveal and resolve those conflicts.

Indeed, there's a lot more detail in the skeleton docs.

It's not crucial to understand those concepts; it's okay if you would prefer to focus on a specific repo like setuptools. But be aware that this repo exists and whatever solution is developed for Setuptools should be applicable for other projects as well. If a patch to the setuptools approach requires lots of mentions of "setuptools", that approach does not generalize well and requires a lot of toil to apply to other projects.

[jaraco]

I prefer having that Tidelift block right in the README.rst that gets rendered on GitHub and PyPI meaning that there's no way to use the dynamic templating but the upside is that you can seamlessly include that readme or a part of it into the index page in sphinx.

The README does currently have a tidelift section, including a badge, and that section already requires customization (replacing PROJECT with the project name for each project).

It does seem possible and even desirable to be able to consolidate these messages... and if the README is the only place the project name needs to be substituted, that's probably acceptable.

I would not want to include the whole of the README, but you suggest including a section. Do you know how that's done? Can this be done in such a way that the "For Enterprise" content is featured prominently in the sidebar (as generated by the table of contents, as seen in urllib3)?

[pradyunsg]

Can you use .. include with stsrt-after and end-before, like Furo does for its homepage and quickstart?

https://pradyunsg.me/furo/quickstart/ (see the "Show Source" button at the bottom)

[webknjaz]

Unlike git subtrees, which creates a separate subdirectory for the content, these repos are merged into the target projects (so common techniques in pyproject.toml or setup.cfg or pytest.ini are stored in the exact same commit), so that as the adopting project evolves, the changes from the skeleton repos can continue to be applied, and the conflicts resolve. The most important feature here is that nothing is copy-pasted around. The code and packaging metadata and tidelift sponsorship concerns evolve independently, but the improvements to the supporting repos can be applied to all of the projects that adopt them. Of course conflicts arise, but the git tooling helps reveal and resolve those conflicts.

Indeed, there's a lot more detail in the skeleton docs.

I'm pretty sure that is still the concept of git subtrees under the hood, in Git. It's a bit more tricky to merge the repo root dir and not a named subdir, but it uses the same set of plumbing operations.

I would not want to include the whole of the README, but you suggest including a section. Do you know how that's done?

This is done on the RST level. You need to use the include directive and :start-after:+:end-before: params. Also, you'll need to add comments with markers to the README itself. Example: https://github.com/sanitizers/octomachinery/blob/94c3eaa/README.rst#L9-L30 + https://github.com/sanitizers/octomachinery/blob/94c3eaa/docs/index.rst#L9-L13.

But you cannot do the same with sidebar because it exists separately from the area where RST documents get rendered. It can only be done on Jinja2 level and would be theme-dependent. But you could add a support.rst document that would show up in the ToC and you could include the same chunk of the README + maybe add some extra text if needed. This is suboptimal but it'd be universal at least.

[webknjaz]

@jaraco here's a solution for you — https://github.com/pypa/setuptools/pull/2708. I don't know where you want it integrated so I'm just showing the demo and leaving it up to you to cherry-pick this approach into the right places.

[jaraco]

Superseded by https://github.com/jaraco/tidelift/commit/918a415b41225f442d6e9b319ecebff19b52a1a5.