Opened 5 years ago

Closed 5 years ago

#19950 closed enhancement (fixed)

docbuild of single file, allow to include underscore method

Reported by: chapoton Owned by:
Priority: minor Milestone: sage-7.1
Component: doctest framework Keywords:
Cc: Merged in:
Authors: Frédéric Chapoton Reviewers: Jori Mäntysalo
Report Upstream: N/A Work issues:
Branch: 5352485 (Commits) Commit: 535248595bfbe7f4fb284a84a85a9ce2490eb9eb
Dependencies: Stopgaps:

Description

The hidden doc can be build using

sage -docbuild -u

but this does not work for a single file. Let us allow that.

later aim: use that in a patchbot plugin.

Change History (12)

comment:1 Changed 5 years ago by chapoton

  • Branch set to public/19950
  • Commit set to b5e3668be99a9e5b6f0b563de3ec628c0b0af5fd
  • Status changed from new to needs_review

New commits:

b5e3668allow the docbuild of a single file to build also underscore methods

comment:2 Changed 5 years ago by git

  • Commit changed from b5e3668be99a9e5b6f0b563de3ec628c0b0af5fd to 535248595bfbe7f4fb284a84a85a9ce2490eb9eb

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

5352485Merge branch 'public/19950' into 7.1.b0

comment:3 Changed 5 years ago by jmantysalo

  • Reviewers set to Jori Mäntysalo

Simple enought for even me to review.

comment:4 Changed 5 years ago by jmantysalo

Stupid question, but...

$ make doc-clean
 . . .
Sage build/upgrade complete!
$ ./sage -docbuild -u file=src/sage/graphs/digraph.py  html
[html     ] loading pickled environment... not yet created
 . . .
Build finished. The built documents can be found in /home/jm58660/.sage/docbuild/digraph/output/html
$ find . -name '*digraph*html'
$

Where is the result?

comment:5 follow-up: Changed 5 years ago by chapoton

The result is in the .sage directory. Just copy-paste /home/jm58660/.sage/docbuild/digraph/output/html in your browser.

comment:6 in reply to: ↑ 5 ; follow-up: Changed 5 years ago by jmantysalo

Replying to chapoton:

The result is in the .sage directory. Just copy-paste /home/jm58660/.sage/docbuild/digraph/output/html in your browser.

Duh, why not in sage-directory? And sorry for dumb question, should have used strace. Or read the output...

When I ran this for posets.py I got doc for posets.is_poset(dig), not for sage.combinat.posets.posets.is_poset(dig). Is this a planned feature?

This does not put functions to index generated by {INDEX_OF_METHODS}. I think that it is not needed, but I mention this in any case.

Seems to work. I will read the code lines little later.

comment:7 in reply to: ↑ 6 ; follow-up: Changed 5 years ago by jhpalmieri

Replying to jmantysalo:

Replying to chapoton:

The result is in the .sage directory. Just copy-paste /home/jm58660/.sage/docbuild/digraph/output/html in your browser.

Duh, why not in sage-directory?

There is no reason to assume that the user has write access to the Sage directory.

When I ran this for posets.py I got doc for posets.is_poset(dig), not for sage.combinat.posets.posets.is_poset(dig). Is this a planned feature?

The original point of the single file docbuilding functionality was to build documentation for a file not in the Sage library. If you're working on a file within Sage, say in src/combinat, then you should probably be doing something like sage --docbuild reference/combinat html

comment:8 in reply to: ↑ 7 ; follow-up: Changed 5 years ago by chapoton

Replying to jhpalmieri:

The original point of the single file docbuilding functionality was to build documentation for a file not in the Sage library. If you're working on a file within Sage, say in src/combinat, then you should probably be doing something like sage --docbuild reference/combinat html

Hum, I would like to use that in the patchbot, to test the hidden doc only in the modified files. Do you think this is not a good idea ? or that it cannot work ?

comment:9 in reply to: ↑ 8 Changed 5 years ago by jhpalmieri

Replying to chapoton:

Replying to jhpalmieri:

The original point of the single file docbuilding functionality was to build documentation for a file not in the Sage library. If you're working on a file within Sage, say in src/combinat, then you should probably be doing something like sage --docbuild reference/combinat html

Hum, I would like to use that in the patchbot, to test the hidden doc only in the modified files. Do you think this is not a good idea ? or that it cannot work ?

It might work, at least if you're just relying on it to flag errors. The output may not look right if it's a Sage library file (saying posets.is_poset rather than sage.combinat.posets.posets.is_poset, for example, and I don't know if there are other problems), but the patchbot won't care about that. Have you tested it on many Sage library files?

comment:10 Changed 5 years ago by chapoton

No, I have only tested that on a few Sage library files so far. Before trying to insert that in the patchbot, this must of course be more thoroughly tested.

comment:11 Changed 5 years ago by jmantysalo

  • Status changed from needs_review to positive_review

Also pdf documentation builds.

comment:12 Changed 5 years ago by vbraun

  • Branch changed from public/19950 to 535248595bfbe7f4fb284a84a85a9ce2490eb9eb
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.