Should use a better sphinx patch to make documentation examples interactive

[pcpa]

I believe the sphinx patch:

- if source.startswith('>>>'):

+ if source.startswith('>>>') or source.startswith('sage: '):

is too much intrusive to be applied on a system wide sphinx (actually, I applied it to Mandriva python-sphinx package long ago...).

But it was required to make examples interactive in my WIP fedora sagemath package using system wide packages.

Component: documentation

Issue created by migration from https://trac.sagemath.org/ticket/13230

[pcpa]

comment:1

I opened a fedora bug report about it also, at https://bugzilla.redhat.com/show_bug.cgi?id=839321

[pcpa]

comment:2

To generate working documentation, I am currently using this hack:

%if %{with_sphinx_hack}
    cp -far %{python_sitelib}/sphinx %{buildroot}%{python_sitearch}
    sed -i "s|\(source.startswith('>>>')\)|\1 or source.startswith('sage: ')|" \
	%{buildroot}%{python_sitearch}/sphinx/highlighting.py
%endif
[...]
%if %{with_sphinx_hack}
    rm -fr %{buildroot}%{python_sitearch}/sphinx
%endif

I still think it would be better to find a better solution, like the suggestion to use

.. code-block:: pycon
    # sage: interactive code

but that probably would require patching almost every source file.

[jhpalmieri]

comment:3

Perhaps it would be better to patch sagenb/notebook/docHTMLProcessor.py and whatever other files produce the live docs from the html docs.

[mkoeppe]

outdated