Scott, Great discovery. We should evaluate these from several points of view and maybe end up supporting all of them :-) since each has its strengths and weaknesses.

On Apr 23, 2021, at 12:33 PM, Scott Kruger <[email protected]> wrote:

I do not know much about these: https://sphinx-comments.readthedocs.io/en/latest/

I'm still not sure a link to a gitlab "New Issue" wouldn't be superior however.

Scott

On 2021-04-23 12:16, Barry Smith did write:

...

Maybe the "edit" code could be copied and modified to go to a new issue window (and stick the URL into the issue) and then let people type. Could it even be clever enough to stick the issue number into the displayed webpage as clickable. Not perfect, but at least we would get notifications for each comment.

Then the page might have a sidebar like

Edit this page Comment, ask question on page

Comment !2345 Comment !4555

Shouldn't Sphinx have such a beast?

Barry

...

On Apr 23, 2021, at 8:50 AM, Patrick Sanan <[email protected]> wrote:

...

Am 23.04.2021 um 04:45 schrieb Barry Smith <[email protected] <mailto:[email protected]>>:

I can edit documentation pages directly from the page now, this is totally awesome but I see no button to comment or ask questions on a page.

I think every page should, by the edit button, have a "Comment, ask questions" button that anyone can click on to make a comment or ask a question about the page. It would be super fantastic if they could refer to particular people in their comments but perhaps that is too difficult.

...

For example I am looking at https://petsc.gitlab.io/-/petsc/-/jobs/1204309863/artifacts/public/overview/... <https://petsc.gitlab.io/-/petsc/-/jobs/1204309863/artifacts/public/overview/features.html> and I immediately want to ask

Where is the TS solver table in the list of solver tables?

Barry

Note the pre-historic PETSc html manual pages which everyone despises have a button in the upper right hand corner to report problems/ask questions so what I am asking for is not unprecedented. Our old code uses email which is not ideal but not ideal is better than not. Surely modern systems like Sphinx have this support built in?

I think the intended way to do this with our Sphinx template would be to add custom HTML templates, which can then be added to the sidebar. https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/sections.htm... <https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/sections.html#add-your-own-html-templates-to-theme-sections>

I'm worried that this involves too much scripting and customization, though. For example here's the way the "edit this page" link is done: https://github.com/pydata/pydata-sphinx-theme/blob/master/pydata_sphinx_them... <https://github.com/pydata/pydata-sphinx-theme/blob/master/pydata_sphinx_theme/_templates/edit-this-page.html>

Doesn't seem too bad but it relies on a pretty big chunk of Python as well: https://github.com/pydata/pydata-sphinx-theme/blob/master/pydata_sphinx_them... <https://github.com/pydata/pydata-sphinx-theme/blob/master/pydata_sphinx_theme/__init__.py#L438>

I'll open an issue on this, though, since it's entirely possible that someone else (or me, later) will think of a simple way to make this work, as it would indeed be a great feature.

-- Scott Kruger Tech-X Corporation [email protected] 5621 Arapahoe Ave, Suite A Phone: (720) 466-3196 Boulder, CO 80303 Fax: (303) 448-7756