Opened 4 years ago
Closed 4 years ago
#23009 closed defect (fixed)
Some .. directives to Sphinx
Reported by:  jmantysalo  Owned by:  

Priority:  minor  Milestone:  sage8.0 
Component:  documentation  Keywords:  
Cc:  tscrim, chapoton  Merged in:  
Authors:  Frédéric Chapoton  Reviewers:  Jori Mäntysalo 
Report Upstream:  N/A  Work issues:  
Branch:  16e364a (Commits, GitHub, GitLab)  Commit:  16e364ac12ca4e0c8d52931a770631d74cb0f80d 
Dependencies:  Stopgaps: 
Description (last modified by )
As an example the warning at make_confluent
at finitely_presented.html
is not shown. This patch corrects some of those.
Useful:
egrep R include=*.py nofilename o '\.\.\s*[AZ]+:' src/sage  sort  uniq c  sort rn
Change History (21)
comment:1 Changed 4 years ago by
 Branch set to u/jmantysalo/somesphinx
comment:2 Changed 4 years ago by
 Cc tscrim chapoton added
 Commit set to d09f6bc774983da6eebaf0c0a538feb6ae483295
 Status changed from new to needs_info
comment:3 Changed 4 years ago by
No idea. I guess it should be replaced by a standard REFERENCES (with no .. at the beginning of every line inside)
comment:4 Changed 4 years ago by
 Commit changed from d09f6bc774983da6eebaf0c0a538feb6ae483295 to 64d75e93757d4ffcd17b8d18d9367cf6741da9aa
Branch pushed to git repo; I updated commit sha1. New commits:
64d75e9  Add a note about directives.

comment:5 followup: ↓ 6 Changed 4 years ago by
you mean
No other block shall be used as a directive
comment:6 in reply to: ↑ 5 Changed 4 years ago by
Replying to chapoton:
you mean
No other block shall be used as a directive
True, must correct that.
 * *
I have never before looked at the patchbot plugins code. The triple colon plugin seems to be simple:
exclude_new(ticket, regex=r':\s*::', msg="Triple colon (:::)", **kwds)
Is it possible to add a plugin to check for Sphinx directives?
comment:7 followup: ↓ 8 Changed 4 years ago by
Regarding "There are exactly five Sphinx directives used in Sage:" I also found .. MATH::
, .. RUBRIC::
, .. AUTOMETHOD::
, .. TOPIC::
. There may be others.
See http://www.sphinxdoc.org/en/stable/rest.html#directives, http://www.sphinxdoc.org/en/stable/markup/index.html#sphinxmarkup, and http://www.sphinxdoc.org/en/stable/extensions.html?highlight=math for some more reST/Sphinx directives. I couldn't find a single comprehensive list anywhere, but I didn't look that hard.
comment:8 in reply to: ↑ 7 ; followup: ↓ 9 Changed 4 years ago by
Replying to jhpalmieri:
Regarding "There are exactly five Sphinx directives used in Sage:" I also found
.. MATH::
,.. RUBRIC::
,.. AUTOMETHOD::
,.. TOPIC::
. There may be others.
I forgot .. MATH::
, thanks. Are others used in Sage?
Is it possible to add own predefined directives? It is odd that we have "special" markup .. NOTE::
but no .. ALGORITHM::
.
Do we have "substructures" in logical sense? I mean something like having a NOTE
explaining something in INPUT
section, some WARNING
inside ALGORITHM
etc?
comment:9 in reply to: ↑ 8 Changed 4 years ago by
Replying to jmantysalo:
Replying to jhpalmieri:
Regarding "There are exactly five Sphinx directives used in Sage:" I also found
.. MATH::
,.. RUBRIC::
,.. AUTOMETHOD::
,.. TOPIC::
. There may be others.I forgot
.. MATH::
, thanks. Are others used in Sage?
Yes: within Sage, do search_src('\.\. [AZ]*::')
.
Is it possible to add own predefined directives? It is odd that we have "special" markup
.. NOTE::
but no.. ALGORITHM::
.
I expect that it is, but I've never tried. In another reality, we could have much more structured docstrings, with .. ALGORITHM::
, .. EXAMPLES::
, .. TESTS::
, etc.
Do we have "substructures" in logical sense? I mean something like having a
NOTE
explaining something inINPUT
section, someWARNING
insideALGORITHM
etc?
I don't know.
comment:10 Changed 4 years ago by
 Description modified (diff)
comment:11 Changed 4 years ago by
 Branch changed from u/jmantysalo/somesphinx to public/23009
 Commit changed from 64d75e93757d4ffcd17b8d18d9367cf6741da9aa to 45b063ef5f7ea9bd18b9bef22a486f96c387639b
comment:12 Changed 4 years ago by
I made a somehwat "large scale cleanup". We should check that doc still builds.
comment:13 Changed 4 years ago by
 Status changed from needs_info to needs_work
At least "No other block shall not be used" error is still there.
Compiling and testing now.
comment:14 Changed 4 years ago by
"use this feature for all  " should start with a capital letter.
(Sidenote: "In a recent paper" is not good, as we of course suppose SageMath to be used for decades to come. :=)
.)
Anyways, this compiles and the documentation compiles. I will run some doctests. I guess we can mark Frédéric as author and I put myself as reviewer. Travis, is this OK?
comment:15 Changed 4 years ago by
 Reviewers set to Jori Mäntysalo
 Status changed from needs_work to positive_review
Passed short tests for all files and long tests for modified file. I think this is OK.
comment:16 followup: ↓ 17 Changed 4 years ago by
What about comment:13?
comment:17 in reply to: ↑ 16 Changed 4 years ago by
 Status changed from positive_review to needs_work
comment:18 Changed 4 years ago by
 Commit changed from 45b063ef5f7ea9bd18b9bef22a486f96c387639b to 16e364ac12ca4e0c8d52931a770631d74cb0f80d
Branch pushed to git repo; I updated commit sha1. New commits:
16e364a  trac 23009 better explanations about sphinx directives

comment:19 Changed 4 years ago by
 Status changed from needs_work to needs_review
ok, I changed the formulation slightly.
comment:21 Changed 4 years ago by
 Branch changed from public/23009 to 16e364ac12ca4e0c8d52931a770631d74cb0f80d
 Resolution set to fixed
 Status changed from positive_review to closed
Please see
src/sage/plot/animate.py
and the line.. REFERENCES (not rendered as a section, but linked inline):
. What is meant there?New commits:
Some Sphinx directives corrected.