Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation for sphinx docs #14969

Merged
merged 8 commits into from Jul 27, 2018

Conversation

Projects
None yet
4 participants
@sidhantnagpal
Copy link
Member

sidhantnagpal commented Jul 24, 2018

Brief description of what is fixed or changed

  • Use LaTeX for docstrings in functions.combinatorial (reference to #14964)
  • Include genocchi and partition numbers in sphinx docs
  • Improve docstrings with single and double backticks for sphinx docs
  • Use plural module names under discrete (discrete.convolutions and discrete.recurrences)
  • Add graphviz as a prerequisite in sympy/doc/README.rst for Debian/Ubuntu
  • Fix links in references containing rounded braces and unicode chars for sphinx docs
  • Miscellaneous improvements to documentation

Other comments

Release Notes

  • discrete
    • rename the submodules discrete.convolution and discrete.recurrence to discrete.convolutions and discrete.recurrences, respectively.

sidhantnagpal added some commits Jul 23, 2018

@sympy-bot

This comment has been minimized.

Copy link

sympy-bot commented Jul 24, 2018

Hi, I am the SymPy bot (v119). I'm here to make sure this pull request has a release notes entry. Please read the guide on how to write release notes.

Click here to see the pull request description that was parsed.

#### Brief description of what is fixed or changed
- Use LaTeX for docstrings in `functions.combinatorial` (reference to #14964)
- Include `genocchi` and `partition` numbers in sphinx docs
- Improve docstrings with single and double backticks for sphinx docs
- Use plural module names under `discrete` (`discrete.convolutions` and `discrete.recurrences`)
- Add `graphviz` as a prerequisite in `sympy/doc/README.rst` for Debian/Ubuntu
- Fix links in references containing rounded braces and unicode chars for sphinx docs
- Miscellaneous improvements to documentation

#### Other comments


#### Release Notes

<!-- BEGIN RELEASE NOTES -->
* discrete
  * rename the submodules `discrete.convolution` and `discrete.recurrence` to `discrete.convolutions` and `discrete.recurrences`, respectively. 
<!-- END RELEASE NOTES -->

Your release notes are in good order.

Here is what the release notes will look like:

  • discrete
    • rename the submodules discrete.convolution and discrete.recurrence to discrete.convolutions and discrete.recurrences, respectively. (#14969 by @sidhantnagpal)

This will be added to https://github.com/sympy/sympy/wiki/Release-Notes-for-1.2.1.

Note: This comment will be updated with the latest check if you edit the pull request. You need to reload the page to see it.

Update

The release notes on the wiki have been updated.

otherwise,
`y(n) = c_0 y(n-1) + c_1 y(n-2) + \cdots + c_{k-1} y(n-k)`
Let `y(n)` be the recurrence of given type, ``c`` be the sequence
of coefficients, ``b`` be the sequence of intial/base values of the

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

intial -> initial

.. math :: y(n) = \begin{cases} b_n & 0 \le n < k \\
y(n) = c_0 y(n-1) + c_1 y(n-2) + \cdots + c_{k-1} y(n-k) & n > k
\end{cases}
Let `x_0, x_1, \cdots, x_n` be a sequence and consider the transformation

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

Perhaps \ldots?

This comment has been minimized.

@sidhantnagpal

sidhantnagpal Jul 25, 2018

Author Member

For every usage?

This comment has been minimized.

@sidhantnagpal

sidhantnagpal Jul 25, 2018

Author Member

It seems existing docstrings contain \dotsb and \dotsc.

Rising factorial (also called Pochhammer symbol) is a double valued
function arising in concrete mathematics, hypergeometric functions
and series expansions. It is defined by:
rf(x, k) = x * (x + 1) * ... * (x + k - 1)
.. math:: rf(x,k) = x*(x+1)* \cdots *(x+k-1)

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

The *s could probably be omitted.

This comment has been minimized.

@sidhantnagpal

sidhantnagpal Jul 25, 2018

Author Member

I was thinking of omitting this, but the definition of rf below for Poly instance seems to be using it (which is required to differentiate functional braces and juxtaposition).

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

Ok. That is logical.

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

Could \cdot be used?

This comment has been minimized.

@sidhantnagpal

sidhantnagpal Jul 25, 2018

Author Member

Yes, it could be rf(x,k) = x \cdot (x+1) \cdots (x+k-1)
and rf(x,k) = x(y) \cdot x(y+1) \cdots x(y+k-1).

recurrence and ``k`` (equal to ``len(c)``) be the order of recurrence.
Then,
.. math :: y(n) = \begin{cases} b_n & 0 \le n < k \\
y(n) = c_0 y(n-1) + c_1 y(n-2) + \cdots + c_{k-1} y(n-k) & n > k
y(n) = c_0 y(n-1) + c_1 y(n-2) + \ldots + c_{k-1} y(n-k) & n > k

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

I think that \cdots is ok here. It is on the same level as +.

\end{cases}
Let `x_0, x_1, \cdots, x_n` be a sequence and consider the transformation
Let `x_0, x_1, \ldots, x_n` be a sequence and consider the transformation

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

\ldots is suitable between commas.

@@ -361,8 +361,8 @@ class factorial2(CombinatorialFunction):
negative integers as:
.. math:: n!! = \begin{cases} 1 & n = 0 \\
n*(n-2)*(n-4)*\cdots *1 & n\ \text{positive odd} \\
n*(n-2)*(n-4)*\cdots *2 & n\ \text{positive even} \\
n(n-2)(n-4) \ldots 1 & n\ \text{positive odd} \\

This comment has been minimized.

@jksuom

jksuom Jul 25, 2018

Member

I think that \cdots is better for multiplication.

sidhantnagpal added some commits Jul 25, 2018

@asmeurer

This comment has been minimized.

Copy link
Member

asmeurer commented Jul 26, 2018

I think it's worth noting the module renames in the release notes (I've updated it).

the sums of products of the elements of the given sequences grouped by
bitwise OR of the corresponding indices.
The covering product of given sequences is a sequence which contains
sum of products of the elements of the given sequences grouped by

This comment has been minimized.

@asmeurer

asmeurer Jul 26, 2018

Member

The sum

bitwise OR of the corresponding indices.
The covering product of given sequences is a sequence which contains
sum of products of the elements of the given sequences grouped by
*bitwise-OR* of the corresponding indices.

This comment has been minimized.

@asmeurer

asmeurer Jul 26, 2018

Member

The bitwise-OR

@@ -432,7 +433,7 @@ def intersecting_product(a, b):
The intersecting product of given sequences is the sequence which
contains the sums of products of the elements of the given sequences
grouped by bitwise AND of the corresponding indices.
grouped by *bitwise-AND* of the corresponding indices.

This comment has been minimized.

@asmeurer

asmeurer Jul 26, 2018

Member

the bitwise-AND

@jksuom

This comment has been minimized.

Copy link
Member

jksuom commented Jul 27, 2018

This looks good, thanks.

@jksuom jksuom merged commit 450b13b into sympy:master Jul 27, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
sympy-bot/release-notes The release notes look OK
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.