Document Sage's documentation style, in particular use ".. FOO::" rather than ".. foo::"

[jhpalmieri]

The preferred style in Sage documentation is for Sphinx directives to be in upper case: .. NOTE:: rather than .. note::, for example. We should document this.

CC: @tscrim

Component: documentation

Author: John Palmieri

Branch/Commit: 7da959b

Reviewer: Travis Scrimshaw

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

[jhpalmieri]

Branch: u/jhpalmieri/NOTE

[jhpalmieri]

Commit: fb1dd0c

[jhpalmieri]

comment:2

This may conflict with #22178. That's easy enough to fix once we're sure #22178 has stabilized.

---

New commits:

fb1dd0c

Trac 22188: Document Sage's documentation style.

[tscrim]

comment:4

I doubt #22178 will change any more, but it will be a trivial fix if git doesn't automatically handle the merge.

[tscrim]

Reviewer: Travis Scrimshaw

[vbraun]

comment:5

PDF docs don't build:

[docpdf] ! You can't use `macro parameter character #' in math mode.
[docpdf] l.3552 <http://www.sphinx-doc.org/rest.html#
[docpdf]                                             citations>_. For links to trac t...

[sagetrac-git]

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

7cfee55

trac 22188: add missing `

[sagetrac-git]

Changed commit from fb1dd0c to 7cfee55

[jhpalmieri]

comment:7

Oops, there was a missing backquote. Should be fixed now.

[kiwifb]

comment:9

Hum, not building html for me on sage-on-gentoo

Error building the documentation.
Traceback (most recent call last):
  File "sage_setup/docbuild/__main__.py", line 2, in <module>
    main()
  File "/scratch2/portage/sci-mathematics/sage-9999/work/sage-9999/src-python2_7/sage_setup/docbuild/__init__.py", line 1667, in main
    builder()
  File "/scratch2/portage/sci-mathematics/sage-9999/work/sage-9999/src-python2_7/sage_setup/docbuild/__init__.py", line 324, in _wrapper
    build_many(build_other_doc, L)
  File "/scratch2/portage/sci-mathematics/sage-9999/work/sage-9999/src-python2_7/sage_setup/docbuild/__init__.py", line 252, in build_many
    ret = x.get(99999)
  File "/usr/lib64/python2.7/multiprocessing/pool.py", line 567, in get
    raise self._value
OSError: [developer] /scratch2/portage/sci-mathematics/sage-9999/work/sage-9999/src-python2_7/doc/en/developer/coding_basics.rst:5: WARNING: Duplicate explicit target name: "sphinx/rest markup for citations".

[kiwifb]

comment:11

See http://stackoverflow.com/questions/5464627/how-to-have-same-text-in-two-links-with-restructured-text

Apparently you need two underscores instead of one in

<http://www.sphinx-doc.org/rest.html#citations>`_

I am guessing in both occurrence of that particular string.

[sagetrac-git]

Changed commit from 7cfee55 to 7da959b

[sagetrac-git]

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

7da959b

trac 22188: fix duplicate reference, reST capitalization

[jhpalmieri]

comment:13

Both citations should point to the same place, so I've changed their targets instead.

[vbraun]

Changed branch from u/jhpalmieri/NOTE to 7da959b