#10080: Fix documentation look in symbolic/expression.pyx
---------------------------------+------------------------------------------
Reporter: kcrisman | Owner: mvngu
Type: enhancement | Status: needs_work
Priority: minor | Milestone: sage-5.7
Component: documentation | Resolution:
Keywords: sd35.5 | Work issues:
Report Upstream: N/A | Reviewers: Travis Scrimshaw
Authors: Kenneth Smith | Merged in:
Dependencies: | Stopgaps:
---------------------------------+------------------------------------------
Changes (by tscrim):
* reviewer: => Travis Scrimshaw
Old description:
> In this file, there are a lot of places where, in the html documentation,
> one sees `TEST` areas that aren't highlighted, methods like
> `simplify_log` referred to but not hyperlinked via `:meth:` (in one case,
> somehow it is only `meth:` by mistake), and so forth. I won't be more
> specific because it's throughout the file - you just have to look. For
> instance, in a number of places there is something like
> {{{
> TESTS::
> sage: asf;dlkj
> }}}
> but since there isn't an intervening empty line this is typeset wrong.
New description:
In this file, there are a lot of places where, in the html documentation,
one sees `TEST` areas that aren't highlighted, methods like `simplify_log`
referred to but not hyperlinked via `:meth:` (in one case, somehow it is
only `meth:` by mistake), and so forth. I won't be more specific because
it's throughout the file - you just have to look. For instance, in a
number of places there is something like
{{{
TESTS::
sage: asf;dlkj
}}}
but since there isn't an intervening empty line this is typeset wrong.
-----
Apply only: [attachment: trac_10080_docstrings_edit.patch]
--
Comment:
Replying to [comment:8 knsam]:
> Replying to [comment:6 tscrim]:
> > Many of the things that were there before were correct (see
[http://www.sagemath.org/doc/developer/conventions.html: the conventions
page]). However the biggest thing to strive for (in a file) is
consistency. For example, every occurrence of {{{True}}} should be typeset
as {{{``True``}}}
>
> I might be mistaken, but I went through them once. I would be glad to
have some pointers for a start about the old style being the right one and
"True".
For example, the `INPUT:` and `OUTPUT:` blocks should be:
{{{
INPUT:
- ``arg_name`` -- Description of argument
- ``second_arg`` -- Another description
OUTPUT:
Describing the output
}}}
Also, for multi-line doctests, it is just `...`, not `....:` (don't ask me
why), I prefer `EXAMPLES:` (with the s no matter if it is 1 or many), and
capitalized `.. SEEALSO::` and such blocks. A good check is to run `sage
-docbuild reference html` (after rebuilding sage via `sage -b`) and look
at the output in `.../sage-branch/doc/output/html/...` in your favorite
web-browser (Firefox had some issues last I knew, this might have been
fixed...).
> Mine is the supposed to be the only patch you apply.
For patchbot:
Apply only: trac_10080_docstrings_edit.patch
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10080#comment:9>
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 unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
