GCI See Also feature

[Harry Rickards]

Hi,

I've been working on bug #2776 (http://code.google.com/p/sympy/issues/detail?id=2776) for Google Code-In (see http://google-melange.appspot.com/gci/task/view/google/gci2011/7132296). I think I've finished it, however before I submit a pull request I'd just like to confirm something. In sphinx, the "See Also" section is put into a yellow box, like the example in the bug report. However, the text inside the yellow box doesn't change (i.e it remains :function:`foobar`). Should this text change to something more user-friendly, or is it just meant to stay as it is?

Many Thanks
Harry Rickards <hric...@gmail.com>

[Alexey U. Gudchenko]

23.11.2011 18:21, Harry Rickards пишет:

Greetings.

Feel free to submit pull requests even if the task is almost done or
just pull request only preliminary, to view and discuss (if you are not
afraid that the code will be stolen by others.) This gives more
specifics about the discussion.

If the work with the branch will be proceeded further, there is not
needed to close/recreate pull request, but just add commits in your
branch and push them to your github remote. Pull request is updated
automatically,

It will be well if the documentation string will like like in the numpy
[1], but the plugin for sphinx must be implemented for it.

As I see your task titled ``See Also`` feature in integrals, is market
as easy, and there are also unrelated similar tasks in the task list:

`See Also`` feature in Number Theory
``See Also`` feature in Combinotorics
``See Also`` feature in integrals
``See Also`` feature in functions
``See Also`` feature in functions/special
``See Also`` feature in Matrices

So it is unrelated with doc generation. But carefully adhere to one
format in the whole file
.
See Also
--------
.submatrix() : extract block from Matrix
.T, diag()

[1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

--
Alexey U.

[Alexey U. Gudchenko]

23.11.2011 19:33, Alexey U. Gudchenko пишет:

P.S.
And note that the above format is an example: in the issue tracker the
format is defined as:

See Also
========

:class:`someclass`, :function:`somefunction`

(use class or function depending on what that object actually is)

However, the exact format depends on how the shinx will be works
correctly with this section.

[Harry Rickards]

2011/11/23 Alexey U. Gudchenko <pr...@goodok.ru>:
<snip>
>> Greetings.

Hi,

>>
>> Feel free to submit pull requests even if the task is almost done or
>> just pull request only preliminary, to view and discuss (if you are not
>> afraid that the code will be stolen by others.) This gives more
>> specifics about the discussion.
>>
>> If the work with the branch will be proceeded further, there is not
>> needed to close/recreate pull request, but just add commits in your
>> branch and push them to your github remote. Pull request is updated
>> automatically,

Ok, great. I've added a pull request on GitHub.

<snip>

>> So it is unrelated with doc generation. But carefully adhere to one
>> format in the whole file
>> .
>>     See Also
>>     --------
>>     .submatrix()   : extract block from Matrix
>>     .T, diag()
>>
>
> P.S.
> And note that the above format is an example: in the issue tracker the
> format is defined as:
>
>    See Also
>    ========
>
>    :class:`someclass`, :function:`somefunction`
>
>    (use class or function depending on what that object actually is)
>
> However, the exact format depends on how the shinx will be works
> correctly with this section.

Ok. I've used the same format in all files, and I plan to (if no-one
else does them first!) do the other "See Also" tasks as well, so I'll
use the same format in those.

Thanks for your help!
Harry Rickards <hric...@gmail.com>

<snip>

[Aaron Meurer]

To reiterate, the docs should look good and consistant in both Sphinx
and in the plain text, because both are used (e.g., the plain text is
what the user will see if he does help(function) in interactive
Python). Personally, I give the plain text appearance higher
precedence over the Sphinx when the two conflict, because the Sphinx
parser can always be changed (e.g., by modifying the numpydoc
extension).

Aaron Meurer