HTML documentation: Show preparsed doctests using inline tabs #37083

mkoeppe · 2024-01-18T06:57:38Z

Every doctest block is decorated with tabs, by default showing the original doctest in Sage syntax, and offering a preparsed, pure Python version of it. The tabs are synchronized across the page.

If @kwankyu's live documentation is being built, it is offered as another tab Sage (live). When this tab is selected, it automatically starts the Thebe/Binder; it is not necessary to find and push the "Make live" button.

Preview

Fixes #35791

📝 Checklist

The title is concise, informative, and self-explanatory.
The description explains in detail what this PR is about.
I have linked a relevant issue or discussion.
I have created tests covering the changes.
I have updated the documentation accordingly.

⌛ Dependencies

…) using inline tabs

… config

…E_PREPARSED_DOC (default yes)

…-preparsed-examples

…o blockers

tobiasdiez · 2024-01-29T07:41:35Z

.ci/merge-fixes.sh

@@ -67,7 +68,7 @@ for REPO in ${SAGE_CI_FIXES_FROM_REPOSITORIES:-sagemath/sage}; do
                        git am --signoff --show-current-patch=diff
                        echo "--------------------------------------------------------------------8<-----------------------------"
                        echo "::endgroup::"
-                        echo "Failure applying $PULL_URL as a patch, resetting"
+                        echo "Failure applying $PULL_SHORT as a patch, resetting"


I like the full URL since it easy to open the corresponding PR. Either way, these changes are unrelated to the actual goal of the PR and thus should be moved to somewhere else.

The full URL appears just above. The improvement is that the repeated one is shortened so that there is not a second, duplicate link.

I'll not open a separate PR for this.

Why not? This is clearly not connected to main theme of this PR.

You've just finished the review of this one line change, no?

No, and there are also more changes here that seem unrelated.

You commented, I responded to your comment. What's missing for the review of this one line change.

The rules of review, spelled out for you:

Provide the necessary information.

Do not use vagueness as a tool.

Do not ask for information that has already been provided.

tobiasdiez · 2024-01-29T07:47:15Z

build/pkgs/sphinx_inline_tabs/type

@@ -0,0 +1 @@
+standard


Adding a new standard package needs a period where it is optional and then a vote on the mailing list first, right?

We don't do that for trivialities.

tobiasdiez · 2024-01-29T07:47:54Z

src/sage_docbuild/__main__.py

@@ -288,6 +288,9 @@ def setup_parser():
    standard.add_argument("--no-plot", dest="no_plot",
                          action="store_true",
                          help="do not include graphics auto-generated using the '.. plot' markup")
+    standard.add_argument("--no-preparsed-examples", dest="no_preparsed_examples",


What's the use case for this option?

It's faster and some people may not want to see the tabs.

Speedwise it doesn't seem to make a change (by looking at the github workflow execution time). Thus, to reduce complexity I prefer to just remove the option here and always build the docs with the parsed python tab.

Noted that this is your preference. I won't remove it.

Why do you want to make this feature configurable?

More rules for review

Check the facts about an unfamiliar domain before making claims about it

Specifically here: Any developer who has worked with the Sage docbuild system knows that we have long had a range of options that configure global aspects of it. There's SAGE_SKIP_PLOT_DIRECTIVE (which you see even in the diff of the present PR...), SAGE_DOC_UNDERSCORE, SAGE_USE_CDNS, and we used to have SAGE_DOC_MATHJAX, SAGE_DOC_JSMATH until recently.

In each of these cases there is a good reason for why the switch exists beyond "some people may not want to" have xyz.

Just a moment ago you denied that the switches even exist.
Now you say they exist but they have a better reason to exist.

This is called "moving the goalposts", a well-known standard technique.

The goalpost stayed the same: we should not add config options to toggle default documentation features off just because "some people may not want to see [xyz]".

Yes, you're repeating yourself.

Just because you have this opinion does not mean that this PR needs work.

kwankyu · 2024-02-06T04:45:45Z

There are overlapped tabs like

This is from

Sage can handle very large numbers, even numbers with millions or billions of
digits.

::

    sage: factorial(100)
    93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000

::

    sage: n = factorial(1000000)  # about 1 second
    sage: len(n.digits())
    5565709

This computes at least 100 digits of :math:`\pi`.

It would be better to separate tabs for the two blocks of examples. Is this possible?

mkoeppe · 2024-02-06T04:54:47Z

Thanks for finding this bug. I'll investigate

…reparse-2

…al blocks

kwankyu · 2024-02-07T14:56:55Z

I tested with live documentation. Very nice.

One suggestion. How about "Live" instead of "Sage (live)"? Short and easy to read, and without parentheses.

Sample view:

mkoeppe · 2024-02-07T17:43:13Z

I think I prefer "Sage (live)" for its clearer semantics ("same language (but a variant)") and extensibility (we can add "Python (live)" later). But I also do have to admit that I generally like parentheses, which is probably related to the amount of time I spent with Lisp in the past~

kwankyu · 2024-02-07T23:05:07Z

I think I prefer "Sage (live)" for its clearer semantics ("same language (but a variant)")

OK. This is just a matter of personal preference, where the author's preference takes precedence.

and extensibility (we can add "Python (live)" later).

That is interesting, though I cannot imagine it now.

But I also do have to admit that I generally like parentheses, which is probably related to the amount of time I spent with Lisp in the past~

I don't like parentheses, as they add branches (obstructions) to the (linear) flow of sentences.

I think I learned it from Knuth's advices on writing: one of the last things he does after writing a sentence is to remove unnecessary parentheses from it.

SageMath version 10.3.beta8, Release Date: 2024-02-13

kwankyu · 2024-02-16T12:17:59Z

How to turn off tabs?

Is it possible to turn off tabs with SAGE_LIVE_DOC=yes?

It seems that

export SAGE_PREPARSED_DOC=no
export SAGE_PREPARSED_DOC=yes

turns on tabs.

mkoeppe · 2024-02-16T16:30:01Z

It seems that
export SAGE_PREPARSED_DOC=no
export SAGE_LIVE_DOC=yes
turns on tabs.

Yes, that's right. Would you prefer the tabless version for this case generally, or as an option?

kwankyu · 2024-02-17T01:16:10Z

I am not sure...

What is the use of the preparsed doc? I guess that primarily advanced users of distribution packages may find it useful. I can imagine that a beginner may become aware of the preparsing mechanism and see how sage syntax is different from python syntax, which is an essential knowledge for effective use of sage.

Users in the middle ground may find tabs (with preparsed doc) just take spaces for information of little use. Having tabs for each example that synchronize anyway seems a waste of space.

I feel that somehow we should have configuration option or switch on pages to support the users in the middle ground. And whatever option or switch we implement should get along with the configuration option and switch for live doc. I am not sure how we could do this without making things too complicated...

mkoeppe · 2024-03-16T18:28:52Z

What is the use of the preparsed doc? I guess that primarily advanced users of distribution packages may find it useful. I can imagine that a beginner may become aware of the preparsing mechanism and see how sage syntax is different from python syntax, which is an essential knowledge for effective use of sage.

Yes, all of that. But it also helps anyone who is already an experienced Python programmer and comes across Sage. It makes it obvious and immediately testable that Sage is actual Python and usable from Python as a library, not some kind of quasi-Python, Python-like, Python-inspired kind of specialty language, or Python with training wheels.

Users in the middle ground may find tabs (with preparsed doc) just take spaces for information of little use. Having tabs for each example that synchronize anyway seems a waste of space.

Yes, the vertical space is precious, which is exactly why I made it disablable.

I feel that somehow we should have configuration option or switch on pages to support the users in the middle ground. And whatever option or switch we implement should get along with the configuration option and switch for live doc. I am not sure how we could do this without making things too complicated...

A persistent switch (is the light/dark selector persistent? using cookies?) for users who only want to see one version and save the vertical space could be an interesting follow-up. But that needs to be done by someone other than me; I stopped following web technologies around 1997;)

kwankyu · 2024-03-16T23:54:19Z

I think I can suggest these for now:

Only two tabs ("original" and "preparsed"). Keep the live doc feature orthogonal to the tabs feature.
Instead of --no-preparsed-examples, use --preparsed-examples to turn on the tabs feature. That is, the default is no tabs. It may get an argument parsed and preparsed to choose the default for the tabs.
Tabs do not synchronize (vertically). Let users be able to switch to preparsed (or original) version only for a particular tab.
Like live doc, turn on the tabs feature in the live doc preview ("deploy-livedoc").

kwankyu · 2024-03-16T23:56:19Z

.. I stopped following web technologies around 1997;)

Nowadays, AI helps humans catch up :-)

mkoeppe · 2024-03-17T00:00:38Z

Tabs do not synchronize (vertically). Let users be able to switch to preparsed (or original) version only for a particular tab.

Why would that possibly be an improvement?

mkoeppe · 2024-03-17T00:08:36Z

Only two tabs ("original" and "preparsed"). Keep the live doc feature orthogonal to the tabs feature.

Why would that be better? I much prefer to click the middle tab instead of having to chase down that shy "Make live" button that lives in hiding near the window frame

kwankyu · 2024-03-17T00:14:22Z

Tabs do not synchronize (vertically). Let users be able to switch to preparsed (or original) version only for a particular tab.

Why would that possibly be an improvement?

I assumed all tabs are already in either "parsed" or "preparsed" by default as the user want. Then the user would want to switch to the other version temporarily for a particular tab.

But right... in my proposal, it is not handy for the user to choose the the default, unless to make a full doc build.

OK. I am not strong about this.

kwankyu · 2024-03-17T00:22:06Z

Only two tabs ("original" and "preparsed"). Keep the live doc feature orthogonal to the tabs feature.

Why would that be better? I much prefer to click the middle tab instead of having to chase down that shy "Make live" button that lives in hiding near the window frame

By having the two features orthogonal, we don't need to add an additional tab for "live preparsed".

But I agree that the button is not so visible...

kwankyu

OK.

Now I am convinced that having live tab is better than inserting live cell below.

kwankyu · 2024-03-20T07:45:29Z

By the way, live doc seems broken (as seen in the doc preview). Perhaps temporarily. Thebe was upgraded to 0.9.0 recently.

mkoeppe · 2024-03-20T08:14:54Z

By the way, live doc seems broken

Are we not pinning the versions of the components there?

kwankyu · 2024-03-20T08:31:25Z

We are using https://unpkg.com/thebe@latest/lib/index.js via patched jupyter-sphinx.

kwankyu · 2024-03-20T09:17:36Z

Fixing in #37637

kwankyu · 2024-03-20T10:56:48Z

You may want these refinements:

diff --git a/src/doc/common/static/custom-jupyter-sphinx.css b/src/doc/common/static/custom-jupyter-sphinx.css
index a68a5cb05aa..e79b47b4539 100644
--- a/src/doc/common/static/custom-jupyter-sphinx.css
+++ b/src/doc/common/static/custom-jupyter-sphinx.css
@@ -1,5 +1,5 @@
 div.jupyter_container {
-  margin: .5rem 0;
+  border: 0;
 }
 
 div.jupyter_container + div.jupyter_container {
diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py
index 145105bb814..1c705c68d1f 100644
--- a/src/sage_docbuild/conf.py
+++ b/src/sage_docbuild/conf.py
@@ -903,7 +903,7 @@ class SagecodeTransform(SphinxTransform):
                             linenostart=1)
                         cell_node += cell_input
                         container = TabContainer("", type="tab", new_set=False)
-                        textnodes = [Text('Sage (live)')]
+                        textnodes = [Text('Sage Live')]
                         label = Label("", "", *textnodes)
                         container += label
                         content = Container("", is_div=True, classes=["tab-content"])

"Sage Live" or "Sage live" (no parentheses please).

(before) (see the double border)

(after)

…reparse-2

…nf.py: Refinements

mkoeppe · 2024-03-20T16:37:39Z

Thank you, committed as dea37e7.

github-actions · 2024-03-20T17:48:54Z

Documentation preview for this PR (built with commit dea37e7; changes) is ready! 🎉

Matthias Koeppe added 9 commits January 17, 2024 22:38

src/sage_docbuild/conf.py: Show preparsed doctests (and Jupyter cells…

d318a49

…) using inline tabs

src/sage_docbuild/conf.py: Include plain Python prompts in copybutton…

10acc0f

… config

src/sage_docbuild/conf.py: Conditionalize on environment variable SAG…

8974bcb

…E_PREPARSED_DOC (default yes)

Merge branch 'sphinx-envvar' into doc-inline-tab-preparse-2

129540c

sage --docbuild: Add option --no-preparsed-examples

6412ce4

src/doc/en/installation/source.rst (SAGE_DOCBUILD_OPTS): Mention --no…

161a7e7

…-preparsed-examples

.github/workflows/[doc-]build[-pdf].yml: Do not fail when there are n…

0034cc9

…o blockers

.ci/merge-fixes.sh: Cosmetic change

d8b0a12

Activate Thebe when "Sage (live)" tab is clicked

84e7c89

tobiasdiez suggested changes Jan 29, 2024

View reviewed changes

mkoeppe added s: needs review c: documentation labels Feb 5, 2024

mkoeppe self-assigned this Feb 5, 2024

mkoeppe added s: needs work and removed s: needs review labels Feb 6, 2024

Matthias Koeppe added 2 commits February 6, 2024 21:07

Merge remote-tracking branch 'upstream/develop' into doc-inline-tab-p…

5c8bfa1

…reparse-2

src/sage_docbuild/conf.py: Do not merge inline tabs of adjacent liter…

57fd4ab

…al blocks

mkoeppe added s: needs review and removed s: needs work labels Feb 7, 2024

Merge tag '10.3.beta8' into doc-inline-tab-preparse-2

abfda0a

SageMath version 10.3.beta8, Release Date: 2024-02-13

tobiasdiez added s: needs work and removed s: needs review labels Feb 14, 2024

mkoeppe added s: needs review and removed s: needs work labels Feb 14, 2024

Merge branch 'develop' into doc-inline-tab-preparse-2

75d0e7d

kwankyu approved these changes Mar 20, 2024

View reviewed changes

kwankyu added s: positive review and removed s: needs review labels Mar 20, 2024

Matthias Koeppe and others added 2 commits March 20, 2024 09:32

Merge remote-tracking branch 'upstream/develop' into doc-inline-tab-p…

f74f017

…reparse-2

src/doc/common/static/custom-jupyter-sphinx.css, src/sage_docbuild/co…

dea37e7

…nf.py: Refinements

vbraun merged commit f81e21f into sagemath:develop Mar 25, 2024
13 checks passed

mkoeppe added this to the sage-10.4 milestone Mar 25, 2024

github-actions bot removed the s: positive review label Mar 26, 2024

HTML documentation: Show preparsed doctests using inline tabs #37083

HTML documentation: Show preparsed doctests using inline tabs #37083

Conversation

mkoeppe commented Jan 18, 2024 • edited Loading

📝 Checklist

⌛ Dependencies

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwankyu commented Feb 6, 2024

mkoeppe commented Feb 6, 2024

kwankyu commented Feb 7, 2024

mkoeppe commented Feb 7, 2024

kwankyu commented Feb 7, 2024

kwankyu commented Feb 16, 2024 • edited Loading

mkoeppe commented Feb 16, 2024

kwankyu commented Feb 17, 2024

mkoeppe commented Mar 16, 2024

kwankyu commented Mar 16, 2024 • edited Loading

kwankyu commented Mar 16, 2024 • edited Loading

mkoeppe commented Mar 17, 2024

mkoeppe commented Mar 17, 2024

kwankyu commented Mar 17, 2024

kwankyu commented Mar 17, 2024

kwankyu left a comment • edited Loading

Choose a reason for hiding this comment

kwankyu commented Mar 20, 2024 • edited Loading

mkoeppe commented Mar 20, 2024

kwankyu commented Mar 20, 2024

kwankyu commented Mar 20, 2024

kwankyu commented Mar 20, 2024

mkoeppe commented Mar 20, 2024

github-actions bot commented Mar 20, 2024

mkoeppe commented Jan 18, 2024 •

edited

Loading

kwankyu commented Feb 16, 2024 •

edited

Loading

kwankyu commented Mar 16, 2024 •

edited

Loading

kwankyu commented Mar 16, 2024 •

edited

Loading

kwankyu left a comment •

edited

Loading

kwankyu commented Mar 20, 2024 •

edited

Loading