#12996: Support for one-dimensional shifts of finite type
--------------------------------------+-------------------------------------
Reporter: mhs | Owner: sage-combinat
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-5.3
Component: combinatorics | Resolution:
Keywords: symbolic dynamics | Work issues:
Report Upstream: N/A | Reviewers:
Authors: Michael Schraudner | Merged in:
Dependencies: | Stopgaps:
--------------------------------------+-------------------------------------
Comment (by slabbe):
> Is there any way to see where exactly they are produced? the numbers
seem not to match line numbers in the .py file. Is there any good
reference for sphinx or the syntax I should use for SAGE to build the doc
without warnings?
>
> Very annoying this sphinx thing!
Yes... it is. The number refers to the line number inside each doctring,
but you don't know which... By chance, we write documentation almost
always the same way and there are few rules to learn. Here is what I
suggest. You first read
http://docutils.sourceforge.net/docs/user/rst/quickref.html
Then, you practice yourself with the script
{{{SAGE_ROOT/local/bin/rst2html.py}}}
For example, you copy a doctring between {{{r"""}}} and {{{"""}}} of your
file into a file {{{fichier.rst}}} like this one:
{{{
INPUT:
- ``init_obj`` - (default: None) can be any of the following:
- a directed (multi)graph
- a square matrix with non-negative integer entries
- a list of forbidden words (over some alphabet) either given as
- a list of strings (with or without symbol separators), e.g.
['11', '123', '4'] (no separator) or ['1.1', '1.2.3', '4']
('.' used as separator)
- a list of lists containing elements of the alphabet, e.g.
[[1, 1], [1, 2, 3], [4]] or [['a', 'a'], ['a', 'b', 'b']]
- a list of instances of the SAGE class Words (over the alphabet),
e.g. [Word("11"), Word(["1", "2", "3"]), Word("4")]
If this parameter is not provided the full-shift over the specified
alphabet will be created. If neither this parameter nor an alphabet
is given the empty shift will be created.
- ``alph`` - (default: None) a list of symbols (the alphabet) used in the
definition of the SFT. If this parameter is not provided a standard
alphabet will be created (whenever possible) from the ``init_obj``. The
elements of the alphabet can be general SAGE objects which do not
contain the substring ``symb_sep`` in their string representation.
Nevertheless it is preferable to use symbols which are either
non-negative integers or short strings (e.g. single letters).
The alphabet is not allowed to contain repetitions (literal copies as
well as symbols whose string representations do coincide) and whenever
its elements have distinct lengths the use of ``symb_sep`` is strongly
advised. We also highly recommend the use of unambiguous alphabets!
}}}
Then, you call the following command on it :
{{{
$ ~/Applications/sage-5.2/local/bin/rst2html.py fichier.rst fichier.html
fichier.rst:14: (WARNING/2) Definition list ends without a blank line;
unexpected unindent.
}}}
Now, the number 14 refers really to the line 14 in the file fichier.rst.
You may also open the html file to see where is the warning :
{{{
$ open fichier.html
}}}
You may also copy and paste docstring into this website I just found and
never used before :
http://rst.ninjs.org/
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/12996#comment:15>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
