Opened 4 years ago

Closed 4 years ago

#23009 closed defect (fixed)

Some .. -directives to Sphinx

Reported by: jmantysalo Owned by:
Priority: minor Milestone: sage-8.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:

Status badges

Description (last modified by chapoton)

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 --no-filename -o '\.\.\s*[A-Z]+:' src/sage | sort | uniq -c | sort -rn

Change History (21)

comment:1 Changed 4 years ago by jmantysalo

  • Branch set to u/jmantysalo/some-sphinx

comment:2 Changed 4 years ago by jmantysalo

  • Cc tscrim chapoton added
  • Commit set to d09f6bc774983da6eebaf0c0a538feb6ae483295
  • Status changed from new to needs_info

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:

d09f6bcSome Sphinx directives corrected.

comment:3 Changed 4 years ago by chapoton

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 git

  • Commit changed from d09f6bc774983da6eebaf0c0a538feb6ae483295 to 64d75e93757d4ffcd17b8d18d9367cf6741da9aa

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

64d75e9Add a note about directives.

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

you mean

No other block shall be used as a directive

comment:6 in reply to: ↑ 5 Changed 4 years ago by jmantysalo

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 follow-up: Changed 4 years ago by jhpalmieri

Regarding "There are exactly five Sphinx directives used in Sage:" I also found .. MATH::, .. RUBRIC::, .. AUTOMETHOD::, .. TOPIC::. There may be others.

See http://www.sphinx-doc.org/en/stable/rest.html#directives, http://www.sphinx-doc.org/en/stable/markup/index.html#sphinxmarkup, and http://www.sphinx-doc.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 ; follow-up: Changed 4 years ago by 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?

Is it possible to add own pre-defined 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 jhpalmieri

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('\.\. [A-Z]*::').

Is it possible to add own pre-defined 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 in INPUT section, some WARNING inside ALGORITHM etc?

I don't know.

Last edited 4 years ago by jhpalmieri (previous) (diff)

comment:10 Changed 4 years ago by chapoton

  • Description modified (diff)

comment:11 Changed 4 years ago by chapoton

  • Branch changed from u/jmantysalo/some-sphinx to public/23009
  • Commit changed from 64d75e93757d4ffcd17b8d18d9367cf6741da9aa to 45b063ef5f7ea9bd18b9bef22a486f96c387639b

New commits:

d35043aMerge branch 'u/jmantysalo/some-sphinx' in 8.0.b8
ba0863dsome correction of blocks
76f29e6Merge chapoton's branch into jmantysalo's branch
45b063elarge cleanup of blocks

comment:12 Changed 4 years ago by chapoton

I made a somehwat "large scale cleanup". We should check that doc still builds.

comment:13 Changed 4 years ago by jmantysalo

  • 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 jmantysalo

"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 jmantysalo

  • Authors changed from Jori Mäntysalo to Frédéric Chapoton
  • 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 follow-up: Changed 4 years ago by jhpalmieri

What about comment:13?

comment:17 in reply to: ↑ 16 Changed 4 years ago by jmantysalo

  • Status changed from positive_review to needs_work

Replying to jhpalmieri:

What about comment:13?

Arghs, forgot that.

comment:18 Changed 4 years ago by git

  • Commit changed from 45b063ef5f7ea9bd18b9bef22a486f96c387639b to 16e364ac12ca4e0c8d52931a770631d74cb0f80d

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

16e364atrac 23009 better explanations about sphinx directives

comment:19 Changed 4 years ago by chapoton

  • Status changed from needs_work to needs_review

ok, I changed the formulation slightly.

comment:20 Changed 4 years ago by jmantysalo

  • Status changed from needs_review to positive_review

LGTM.

comment:21 Changed 4 years ago by vbraun

  • Branch changed from public/23009 to 16e364ac12ca4e0c8d52931a770631d74cb0f80d
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.