Opened 5 years ago

Closed 5 years ago

#22188 closed enhancement (fixed)

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

Reported by: jhpalmieri Owned by:
Priority: minor Milestone: sage-7.6
Component: documentation Keywords:
Cc: tscrim Merged in:
Authors: John Palmieri Reviewers: Travis Scrimshaw
Report Upstream: N/A Work issues:
Branch: 7da959b (Commits, GitHub, GitLab) Commit: 7da959b1d6f93a2b2c9d32bfe7b0176c5bae279f
Dependencies: Stopgaps:

Status badges

Description

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.

Change History (14)

comment:1 Changed 5 years ago by jhpalmieri

  • Branch set to u/jhpalmieri/NOTE

comment:2 Changed 5 years ago by jhpalmieri

  • Commit set to fb1dd0c7b0ca83563046ffba7119cdeabacfe1f6

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


New commits:

fb1dd0cTrac 22188: Document Sage's documentation style.

comment:3 Changed 5 years ago by jhpalmieri

  • Status changed from new to needs_review

comment:4 Changed 5 years ago by tscrim

  • Reviewers set to Travis Scrimshaw
  • Status changed from needs_review to positive_review

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

comment:5 Changed 5 years ago by vbraun

  • Status changed from positive_review to needs_work

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...

comment:6 Changed 5 years ago by git

  • Commit changed from fb1dd0c7b0ca83563046ffba7119cdeabacfe1f6 to 7cfee554981cdcbf43b5b7da3793404913ef3540

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

7cfee55trac 22188: add missing `

comment:7 Changed 5 years ago by jhpalmieri

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

comment:8 Changed 5 years ago by tscrim

  • Status changed from needs_work to positive_review

comment:9 Changed 5 years ago by fbissey

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

comment:10 Changed 5 years ago by vbraun

  • Status changed from positive_review to needs_work

comment:11 Changed 5 years ago by fbissey

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.

comment:12 Changed 5 years ago by git

  • Commit changed from 7cfee554981cdcbf43b5b7da3793404913ef3540 to 7da959b1d6f93a2b2c9d32bfe7b0176c5bae279f

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

7da959btrac 22188: fix duplicate reference, reST capitalization

comment:13 Changed 5 years ago by jhpalmieri

  • Status changed from needs_work to needs_review

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

comment:14 Changed 5 years ago by vbraun

  • Branch changed from u/jhpalmieri/NOTE to 7da959b1d6f93a2b2c9d32bfe7b0176c5bae279f
  • Resolution set to fixed
  • Status changed from needs_review to closed
Note: See TracTickets for help on using tickets.