Some clean up in docbuilding

Question

Some clean up in docbuilding

jdemeyer opened this issue 10 years ago · 52 comments

jdemeyer commented 10 years ago

No change in functionality, just some clean up.

In particular:

move the code for running Sphinx to src/sage_setup/docbuild
do not create and delete empty directories, instead silence the Sphinx warnings about non-existing directories
instead of compile(), use import
add a new variable SAGE_DOC_OUTPUT for src/doc/output (this is moved to local/share/doc/sage in #19963)

Depends on #19950

CC: @hivert @nathanncohen

Component: build

Author: Jeroen Demeyer

Branch: 0455d14

Reviewer: Marc Mezzarobba

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

Answer 1 · 2015-09-03T15:58:24.000Z

Branch: u/jdemeyer/ticket/19127

Answer 2 · 2015-09-03T15:58:53.000Z

Commit: 2e2cb7a

Answer 3 · 2015-09-03T15:58:53.000Z

New commits:

`2e2cb7a`	`Docbuilder cleanup`

Answer 4 · 2015-09-03T19:48:35.000Z

Changed commit from 2e2cb7a to d959af4

Answer 5 · 2015-09-03T19:48:35.000Z

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

`d959af4`	`builder/__init__.py should not be executable`

Answer 6 · 2015-09-08T20:38:49.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`ff58c9c`	`Replace conf.py copies by symlinks`
`d783ee1`	`Docbuilder cleanup`

Answer 7 · 2015-09-08T20:38:49.000Z

Changed commit from d959af4 to d783ee1

Answer 8 · 2015-09-08T20:39:09.000Z

Dependencies: #19166

Answer 9 · 2015-11-07T11:47:36.000Z

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

`9b12694`	`Merge tag '6.10.beta3' into t/19127/ticket/19127`

Answer 10 · 2015-11-07T11:47:36.000Z

Changed commit from d783ee1 to 9b12694

Answer 11 · 2016-01-10T21:51:55.000Z

Changed commit from 9b12694 to 97a6f82

Answer 12 · 2016-01-10T21:51:55.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`97a6f82`	`Merge tag '7.0.beta3' into t/19127/ticket/19127`

Answer 13 · 2016-01-10T21:52:31.000Z

Changed dependencies from #19166 to none

Answer 14 · 2016-01-24T10:36:35.000Z

Changed commit from 97a6f82 to ea7efaa

Answer 15 · 2016-01-24T10:36:35.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`ea7efaa`	`Docbuilder cleanup`

Answer 16 · 2016-01-25T10:29:44.000Z

Changed commit from ea7efaa to f0f0e4c

Answer 17 · 2016-01-25T10:29:44.000Z

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

`f0f0e4c`	Use `__main__` to run docbuilder

Answer 18 · 2016-01-25T14:07:38.000Z

Changed commit from f0f0e4c to 2fbfe8e

Answer 19 · 2016-01-25T14:07:38.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`2fbfe8e`	`Docbuilder cleanup`

Answer 20 · 2016-01-25T14:08:05.000Z

Description changed:

--- 
+++ 
@@ -1,7 +1,7 @@
 No change in functionality, just some clean up.
 
 In particular:
-- move the code for running Sphinx to `src/doc/builder`
+- move the code for running Sphinx to `src/sage_setup/docbuild`
 - do not create and delete empty directories, instead silence the Sphinx warnings about non-existing directories
 - instead of `compile()`, use `import`
 - add a new variable `SAGE_DOC_OUTPUT` for `src/doc/output` (with the idea that this might be moved to `local/share/doc` in the future)

Answer 21 · 2016-01-25T17:10:12.000Z

Changed commit from 2fbfe8e to 93339c2

Answer 22 · 2016-01-25T17:10:12.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`93339c2`	`Docbuilder cleanup`

Answer 23 · 2016-01-25T21:06:04.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`67b8e35`	`Docbuilder cleanup`

Answer 24 · 2016-01-25T21:06:04.000Z

Changed commit from 93339c2 to 67b8e35

Answer 25 · 2016-01-26T07:29:55.000Z

Changed commit from 67b8e35 to 7c98158

Answer 26 · 2016-01-26T07:29:55.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`7c98158`	`Docbuilder cleanup`

Answer 27 · 2016-01-26T11:30:02.000Z

comment:17

I don't understand what SAGE_DOC_OUTPUT is supposed to do: I tried (without reading the code)

SAGE_DOC_OUTPUT=. sage -docbuild tutorial pdf

but the pdf file still ends up at its usual location.

Answer 28 · 2016-01-26T11:37:14.000Z

comment:18

Replying to @mezzarobba:

I don't understand what SAGE_DOC_OUTPUT is supposed to do

Such variables really need an absolute path, not relative.

Answer 29 · 2016-01-26T14:03:38.000Z

comment:19

LGTM. Two minor comments though:

I wonder why you renamed the logger to doc.builder (the obvious reason to change the name would be to follow the more-or-less standard convention of “namespacing” it using the corresponding Python module name, but that's not what you do).
The developer guide contains a mention of SAGE_ROOT/src/doc/builder/__init__.py that probably should be updated or removed.

Answer 30 · 2016-01-26T14:26:54.000Z

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

`537d9d2`	`Minor fixes`

Answer 31 · 2016-01-26T14:26:54.000Z

Changed commit from 7c98158 to 537d9d2

Answer 32 · 2016-01-26T14:31:30.000Z

Reviewer: Marc Mezzarobba

Answer 33 · 2016-01-27T10:35:22.000Z

Description changed:

--- 
+++ 
@@ -4,4 +4,4 @@
 - move the code for running Sphinx to `src/sage_setup/docbuild`
 - do not create and delete empty directories, instead silence the Sphinx warnings about non-existing directories
 - instead of `compile()`, use `import`
-- add a new variable `SAGE_DOC_OUTPUT` for `src/doc/output` (with the idea that this might be moved to `local/share/doc` in the future)
+- add a new variable `SAGE_DOC_OUTPUT` for `src/doc/output` (this is moved to `local/share/doc/sage` in #19963)

Answer 34 · 2016-01-28T17:13:58.000Z

comment:23

http://build.sagedev.org/release/builders/%20%20fast%20Volker%20Desktop%20%28Fedora%2022%20x86_64%29%20incremental/builds/366/steps/shell_4/logs/stdio

Answer 35 · 2016-01-28T18:22:35.000Z

comment:24

That failure looks unrelated to the documentation, so I would be surprised if that buildbot error was due to this ticket. Which other tickets did you test?

Answer 36 · 2016-01-28T18:36:32.000Z

comment:25

Unrelated to the doctest failure: should the clean target in src/doc/Makefile also do something like rm -f common/*.pyc? It would be good to clean up common/builder.pyc and other left-over files.

Answer 37 · 2016-01-28T19:04:14.000Z

comment:26

Replying to @vbraun:

http://build.sagedev.org/release/builders/%20%20fast%20Volker%20Desktop%20%28Fedora%2022%20x86_64%29%20incremental/builds/366/steps/shell_4/logs/stdio

Confirmed (but still surprising!)

Answer 38 · 2016-01-28T19:15:05.000Z

comment:27

The problem seems to be that doctesting the old src/doc/output files fails because they are no longer consider "Sage library" files. Easily fixed by removing src/doc/output.

Answer 39 · 2016-01-28T19:36:36.000Z

Changed commit from 537d9d2 to 2b37da3

Answer 40 · 2016-01-28T19:36:36.000Z

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

`2b37da3`	`Remove old src/doc/ouput and .pyc files`

Answer 41 · 2016-01-28T22:47:49.000Z

comment:29

Oops, I was confusing this ticket with #19963. Never mind this last commit.

Answer 42 · 2016-01-28T22:50:08.000Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

Answer 43 · 2016-01-28T22:50:08.000Z

Changed commit from 2b37da3 to 537d9d2

Answer 44 · 2016-01-29T06:57:36.000Z

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

`2f8fe6b`	`Use force_lib=True for "doc" modules`

Answer 45 · 2016-01-29T06:57:36.000Z

Changed commit from 537d9d2 to 2f8fe6b

Answer 46 · 2016-01-29T07:06:51.000Z

comment:33

I will merge #19950 because these tickets conflict.

Answer 47 · 2016-01-29T07:06:51.000Z

Dependencies: #19950

Answer 48 · 2016-01-29T07:09:07.000Z

Changed commit from 2f8fe6b to 0455d14

Answer 49 · 2016-01-29T07:09:07.000Z

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

`b5e3668`	`allow the docbuild of a single file to build also underscore methods`
`5352485`	`Merge branch 'public/19950' into 7.1.b0`
`0455d14`	`Merge remote-tracking branch 'trac/public/19950' into t/19127/ticket/19127`

Answer 50 · 2016-02-02T23:06:38.000Z

Changed branch from u/jdemeyer/ticket/19127 to 0455d14

Answer 51 · 2016-03-30T07:32:11.000Z

Changed commit from 0455d14 to none

Answer 52 · 2016-03-30T07:32:11.000Z

comment:37

Is this the reason for #20255?