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:  sage7.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
 Branch set to public/19950
 Commit set to b5e3668be99a9e5b6f0b563de3ec628c0b0af5fd
 Status changed from new to needs_review
comment:2 Changed 5 years ago by
 Commit changed from b5e3668be99a9e5b6f0b563de3ec628c0b0af5fd to 535248595bfbe7f4fb284a84a85a9ce2490eb9eb
Branch pushed to git repo; I updated commit sha1. New commits:
5352485  Merge branch 'public/19950' into 7.1.b0

comment:3 Changed 5 years ago by
 Reviewers set to Jori Mäntysalo
Simple enought for even me to review.
comment:4 Changed 5 years ago by
Stupid question, but...
$ make docclean . . . 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 followup: ↓ 6 Changed 5 years ago by
The result is in the .sage
directory. Just copypaste /home/jm58660/.sage/docbuild/digraph/output/html
in your browser.
comment:6 in reply to: ↑ 5 ; followup: ↓ 7 Changed 5 years ago by
Replying to chapoton:
The result is in the
.sage
directory. Just copypaste/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 ; followup: ↓ 8 Changed 5 years ago by
Replying to jmantysalo:
Replying to chapoton:
The result is in the
.sage
directory. Just copypaste/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 forposets.is_poset(dig)
, not forsage.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 ; followup: ↓ 9 Changed 5 years ago by
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 likesage 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
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 likesage 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
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
 Status changed from needs_review to positive_review
Also pdf documentation builds.
comment:12 Changed 5 years ago by
 Branch changed from public/19950 to 535248595bfbe7f4fb284a84a85a9ce2490eb9eb
 Resolution set to fixed
 Status changed from positive_review to closed
New commits:
allow the docbuild of a single file to build also underscore methods