Remove runtime dependency on sage_docbuild introduced in #33763

Question

Remove runtime dependency on sage_docbuild introduced in #33763

mkoeppe opened this issue 3 years ago · 34 comments

We create a new module sage.misc.sagedoc_conf, to which we move the parts of sage_docbuild.conf needed by sage.misc.sphinxify.

Depends on #33922

CC: @kwankyu @jhpalmieri @antonio-rojas

Component: documentation

Author: Matthias Koeppe, Kwankyu Lee

Branch/Commit: 0a02496

Reviewer: Kwankyu Lee, Matthias Koeppe

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

Answer 1 · 2022-06-09T23:40:41.000Z

Description changed:

--- 
+++ 
@@ -1,3 +1,4 @@
 (from [#33763 comment:19](https://github.com/sagemath/sage/issues/33763#comment:19))
 
+We create a new module `sage.misc.sagedoc_conf`, to which we move the parts of `sage_docbuild.conf` needed by `sage.misc.sphinxify`.

Answer 2 · 2022-06-10T00:32:58.000Z

Branch: u/mkoeppe/remove_runtime_dependency_on_sage_docbuild_introduced_in__33763

Answer 3 · 2022-06-10T00:38:15.000Z

Commit: f2b34ae

Answer 4 · 2022-06-10T00:38:15.000Z

Author: Matthias Koeppe

Answer 5 · 2022-06-10T00:38:15.000Z

New commits:

`2915352`	`src/sage/misc/sagedoc_conf.py: New, use it instead of sage_docbuild.conf`
`f2b34ae`	`src/sage/misc/sagedoc_conf.py: Move default_role here from sage_docbuild.conf`

Answer 6 · 2022-06-10T00:53:50.000Z

comment:4

This one setting is what is needed to pass the doctests of sage.misc.sagedoc.
Not sure what else is needed

Answer 7 · 2022-06-10T01:46:51.000Z

comment:5

I was waiting for the next beta that is merged with #33922, before I start to work on this ticket.

I think many more settings in sage_docbuild/conf.py need to move into sage/misc/sagedoc_conf.py, in anticipation of #33682.

Answer 8 · 2022-06-17T03:21:38.000Z

Changed commit from f2b34ae to none

Answer 9 · 2022-06-17T03:21:38.000Z

Changed branch from u/mkoeppe/remove_runtime_dependency_on_sage_docbuild_introduced_in__33763 to u/klee/33936

Answer 10 · 2022-06-17T03:21:55.000Z

Commit: 7b17c2d

Answer 11 · 2022-06-17T03:21:55.000Z

Branch pushed to git repo; I updated commit sha1. New commits:

`9fa7101`	`Add missing title to conf.py`
`7b17c2d`	`Split sage_docbuild.conf to sage.misc.sagedoc_conf`

Answer 12 · 2022-06-17T03:22:39.000Z

Changed author from Matthias Koeppe to Matthias Koeppe, Kwankyu Lee

Answer 13 · 2022-06-17T03:25:07.000Z

Dependencies: #33922

Answer 14 · 2022-06-17T03:38:04.000Z

Changed commit from 7b17c2d to 282270f

Answer 15 · 2022-06-17T03:38:04.000Z

Branch pushed to git repo; I updated commit sha1. New commits:

`282270f`	`Fix docs`

Answer 16 · 2022-06-17T03:41:16.000Z

comment:12

I moved more settings which seem to have been used by sphinxify.

Answer 17 · 2022-06-17T19:09:04.000Z

comment:13

I'm not very comfortable with the use of the os.environ variables in sagedoc_conf. I think it would be best if this was done in the docbuild only

Answer 18 · 2022-06-18T08:47:30.000Z

comment:14

Replying to @mkoeppe:

I'm not very comfortable with the use of the os.environ variables in sagedoc_conf. I think it would be best if this was done in the docbuild only

os.environ is used in two places:

(1) in skip_member(): skip_member() skips problematic members of a module.

(2) in setup() to decide whether or not to include skip_TESTS_block(): skip_TESTS_block() skips TESTS: blocks.

For (1), SAGE_CHECK_NESTED and SAGE_DOC_UNDERSCORE environment variables are used

For (2), SAGE_SKIP_TESTS_BLOCKS environment variables is used.

If we decide on the defaults to these 3 variables, then we can remove them from sagedoc_conf. What would be reasonable defaults?

Answer 19 · 2022-06-18T10:21:19.000Z

comment:15

Replying to @kwankyu:

If we decide on the defaults to these 3 variables, then we can remove them from sagedoc_conf. What would be reasonable defaults?

We may remove skip_member() altogether, and include skip_TESTS_block().

Answer 20 · 2022-06-18T10:22:49.000Z

Branch pushed to git repo; I updated commit sha1. New commits:

`c2766bf`	`Move skip_member() to sage_docbuild`

Answer 21 · 2022-06-18T10:22:49.000Z

Changed commit from 282270f to c2766bf

Answer 22 · 2022-06-19T20:36:43.000Z

comment:17

Replying to @sagetrac-git:

Branch pushed to git repo; I updated commit sha1. New commits:

`c2766bf`	`Move skip_member() to sage_docbuild`

It's not completely moved it seems

sage: integrate?
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [1], in <cell line: 1>()
----> 1 get_ipython().run_line_magic('pinfo', 'integrate')

[...]

File /usr/lib/python3.10/site-packages/sage/misc/sagedoc_conf.py:160, in setup(app)
    158 app.connect('autodoc-process-docstring', process_inherited)
    159 app.connect('autodoc-process-docstring', skip_TESTS_block)
--> 160 app.connect('autodoc-skip-member', skip_member)
    161 app.add_transform(SagemathTransform)

NameError: name 'skip_member' is not defined

Answer 23 · 2022-06-20T00:28:51.000Z

Changed commit from c2766bf to 4296851

Answer 24 · 2022-06-20T00:28:51.000Z

Branch pushed to git repo; I updated commit sha1. New commits:

`4296851`	`Move the remnants of skip_member from sagedoc_conf`

Answer 25 · 2022-06-20T00:30:03.000Z

comment:19

Replying to @antonio-rojas:

It's not completely moved it seems

Obviously my mistake. Fixed now.

Answer 26 · 2022-06-25T22:02:13.000Z

comment:20

+    assert app.srcdir.startswith(SAGE_DOC_SRC)

I think this is not a good change because sage -docbuild is also used by user packages

Answer 27 · 2022-06-26T10:31:46.000Z

Changed commit from 4296851 to 0a02496

Answer 28 · 2022-06-26T10:31:46.000Z

Branch pushed to git repo; I updated commit sha1. New commits:

`45f9ff3`	`Merge branch 'develop'`
`0a02496`	`Change assert back to if`

Answer 29 · 2022-06-26T10:33:15.000Z

comment:22

Replying to @mkoeppe:

+    assert app.srcdir.startswith(SAGE_DOC_SRC)
I think this is not a good change because sage -docbuild is also used by user packages

Okay. Removed assert and restored if.

Answer 30 · 2022-06-29T23:20:30.000Z

Reviewer: ..., Matthias Koeppe

Answer 31 · 2022-06-29T23:20:30.000Z

comment:23

positive review from my side

Answer 32 · 2022-06-30T00:29:46.000Z

Changed reviewer from ..., Matthias Koeppe to Kwankyu Lee, Matthias Koeppe

Answer 33 · 2022-06-30T00:29:46.000Z

comment:24

Thank you.

Answer 34 · 2022-07-09T22:33:58.000Z

Changed branch from u/klee/33936 to 0a02496