Repository: sympy/sympy
Pull request: Added examples for hyper.appellf1 and Znm
<!-- Your title above should be a short description of what
was changed. Do not include the issue number in the title. -->

#### References to other Issues or PRs
<!-- If this pull request fixes an issue, write "Fixes #NNNN" in that exact
format, e.g. "Fixes #1234" (see
https://tinyurl.com/auto-closing for more information). Also, please
write a comment on that issue linking back to this pull request once it is
open. -->
Fixes #17887

#19591


#### Brief description of what is fixed or changed
Updated Functions.special submodule :
- Added examples for hyper.appellf1 in hyper.py
- Added examples for Znm in spherical_harmonics.py


#### Release Notes

<!-- Write the release notes for this release below. See
https://github.com/sympy/sympy/wiki/Writing-Release-Notes for more information
on how to write release notes. The bot will check your release notes
automatically to see if they are formatted correctly. -->

<!-- BEGIN RELEASE NOTES -->
NO ENTRY
<!-- END RELEASE NOTES -->

Problem statement:
Add missing docstring sections in Special submodule
As part of my Google Season of Docs project with SymPy, I copy edited all of the docstrings in the Special submodule to reflect the new SymPy Docstring Style Guide. While editing, I came across some docstrings that were missing sections or had other issues that need to be addressed. Here is a list of all of the functions in the Special submodule that had an issue and what needs to be fixed:

1. Jn_zeros 
Parameters listed but does not have a parameters section

2. Bspline_basis, bspline_basis_set
In bspline_basis, parameters not pulling into HTML site
Both have parameters listed but do not have a parameters section

3. Interpolating_spline
Parameters listed but does not have a parameters section

4. Fdiff, eval (under DiracDelta)
Parameters listed but do not have a parameters section

5. Fdiff, eval (under Heaviside)
Parameters listed but do not have a parameters section

6. E1(z)
Missing examples section

7. Li (in error functions)
In the Examples section, the example for under the text “Defining the ``li`` function via an integral:” is missing

8. Hyper
Lists properties as part of this class that need to be their own docstrings with their own examples

9. Meijerg
Lists properties as part of this class that need to be their own docstrings with their own examples

10. Appellf1
Missing examples section

11. Jacobi_normalized
Parameters listed but does not have a parameters section

12. Ynm_c
Missing examples section
Parameters listed but does not have a parameters section

13. Znm
Missing examples section


CC @sympy/gsod

Hints from issue discussion:
For anyone fixing this be sure to follow the documentation style guide https://docs.sympy.org/dev/documentation-style-guide.html
Hey can you assign me this issue? Also, where can I reach out for questions?
Contributors are not assigned with issues here. Anyone can start working and send a relevant PR solving that issue! Also, you can ask questions on this thread or on the mailing list.
I am facing an error when i run ```make html``` after installing prerequisites. Should I state my problem here or create an issue?
Just state it here. We can open an new issue if we determine there is a bug in the build process, but most likely there is some issue on your system. 
I am facing this error when I run ```make html``` inside doc:
```
rm -rf _build/logo
mkdir -p _build/logo
python ./generate_logos.py -d
INFO:root: File saved: ./_build/logo/sympy-notail.svg
INFO:root: File saved: ./_build/logo/sympy-notailtext.svg
INFO:root: File saved: ./_build/logo/sympy-notext.svg
DEBUG:root:command: rsvg-convert ./src/logo/sympy.svg -f png -o ./_build/logo/sympy-160px.png -h 160 -w 160
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./src/logo/sympy.svg -f png -o ./_build/logo/sympy-500px.png -h 500 -w 500
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notail.svg -f png -o ./_build/logo/sympy-notail-160px.png -h 160 -w 160
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notail.svg -f png -o ./_build/logo/sympy-notail-500px.png -h 500 -w 500
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notailtext.svg -f png -o ./_build/logo/sympy-notailtext-160px.png -h 160 -w 160
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notailtext.svg -f png -o ./_build/logo/sympy-notailtext-500px.png -h 500 -w 500
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notext.svg -f png -o ./_build/logo/sympy-notext-160px.png -h 160 -w 160
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notext.svg -f png -o ./_build/logo/sympy-notext-500px.png -h 500 -w 500
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./src/logo/sympy.svg -f png -o ./_build/logo/sympy-16px.png -h 16 -w 16
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./src/logo/sympy.svg -f png -o ./_build/logo/sympy-32px.png -h 32 -w 32
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./src/logo/sympy.svg -f png -o ./_build/logo/sympy-48px.png -h 48 -w 48
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./src/logo/sympy.svg -f png -o ./_build/logo/sympy-64px.png -h 64 -w 64
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notail.svg -f png -o ./_build/logo/sympy-notail-16px.png -h 16 -w 16
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notail.svg -f png -o ./_build/logo/sympy-notail-32px.png -h 32 -w 32
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notail.svg -f png -o ./_build/logo/sympy-notail-48px.png -h 48 -w 48
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notail.svg -f png -o ./_build/logo/sympy-notail-64px.png -h 64 -w 64
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notailtext.svg -f png -o ./_build/logo/sympy-notailtext-16px.png -h 16 -w 16
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notailtext.svg -f png -o ./_build/logo/sympy-notailtext-32px.png -h 32 -w 32
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notailtext.svg -f png -o ./_build/logo/sympy-notailtext-48px.png -h 48 -w 48
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notailtext.svg -f png -o ./_build/logo/sympy-notailtext-64px.png -h 64 -w 64
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notext.svg -f png -o ./_build/logo/sympy-notext-16px.png -h 16 -w 16
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notext.svg -f png -o ./_build/logo/sympy-notext-32px.png -h 32 -w 32
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notext.svg -f png -o ./_build/logo/sympy-notext-48px.png -h 48 -w 48
DEBUG:root:return code: 0
DEBUG:root:command: rsvg-convert ./_build/logo/sympy-notext.svg -f png -o ./_build/logo/sympy-notext-64px.png -h 64 -w 64
DEBUG:root:return code: 0
ERROR:root:Return code is not 0: Command: convert ./_build/logo/sympy-16px.png ./_build/logo/sympy-32px.png ./_build/logo/sympy-48px.png ./_build/logo/sympy-64px.png ./_build/logo/sympy-favicon.ico
ERROR:root:return code: 1
Makefile:143: recipe for target 'logo' failed
make: *** [logo] Error 1
```

Here are the commands I ran from the start to build:

```
git clone git://github.com/sympy/sympy.git
cd sympy
git remote add github git@github.com:Soumi7/sympy.git
conda create -n sympy-dev-py35 python=3.5 mpmath flake8
source activate sympy-dev-py35
flake8 sympy
python setup.py install
git branch branch1
git checkout branch1
sudo apt-get install python-sphinx texlive-latex-recommended dvipng librsvg2-bin imagemagick docbook2x graphviz
sudo apt-get update
python -m pip install sphinx-math-dollar
ls
cd doc
make html
```



It looks like the generate logos script doesn't print the stdout and stderr when there is an error, so we can't tell what the problem is. This should be fixed. 

What is the output if you run

```
cd doc
convert ./_build/logo/sympy-16px.png ./_build/logo/sympy-32px.png ./_build/logo/sympy-48px.png ./_build/logo/sympy-64px.png ./_build/logo/sympy-favicon.ico
```
I installed  `imagemagick` with apt-get. However , I was unable to convert the PG delegate to yes after configuring:
```
./configure --with-png=yes 
```


I reinstalled **imagemagick from source** and that error has **gone**! 
The logo generated but i got this error:

```
Running Sphinx v3.0.3

Exception occurred:
  File "/home/soumi/anaconda3/envs/sympy-dev-py35/lib/python3.5/site-packages/matplotlib/sphinxext/plot_directive.py", line 262, in setup
    app.add_directive('plot', plot_directive, True, (0, 2, False), **options)
TypeError: add_directive() got an unexpected keyword argument 'format'
The full traceback has been saved in /tmp/sphinx-err-arpru3bc.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:49: recipe for target 'html' failed
make: *** [html] Error 2
```
It gives different error messages everytime I run it:
```
Exception occurred:
  File "/home/soumi/anaconda3/envs/sympy-dev-py35/lib/python3.5/site-packages/matplotlib/sphinxext/plot_directive.py", line 262, in setup
    app.add_directive('plot', plot_directive, True, (0, 2, False), **options)
TypeError: add_directive() got an unexpected keyword argument 'height'
The full traceback has been saved in /tmp/sphinx-err-s1h2y1is.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:49: recipe for target 'html' failed
make: *** [html] Error 2
```
My Matplotlib version is
 ```
>>> matplotlib.__version__
'3.0.3'
```

My python version is :
```
Python 3.5.6 :: Anaconda, Inc.
```

My guess is that the matplotlib version is too old. The latest version is 3.2.1.

Commit message: Added examples for hyper.appellf1 and Znm

Patch to review:
diff --git a/sympy/functions/special/hyper.py b/sympy/functions/special/hyper.py
index 51d9507f76ed..ad4ef38e5965 100644
--- a/sympy/functions/special/hyper.py
+++ b/sympy/functions/special/hyper.py
@@ -1100,6 +1100,16 @@ class appellf1(Function):
         \frac{(a)_{m+n} (b_1)_m (b_2)_n}{(c)_{m+n}}
         \frac{x^m y^n}{m! n!}.
 
+    Examples
+    ========
+    >>> from sympy.functions.special.hyper import appellf1
+    >>> appellf1(2., 1., 6., 4., 5., 6.)
+    0.0063339426292673
+    >>> appellf1(1,2,3,5,0.5,0.25)
+    appellf1(1, 2, 3, 5, 0.5, 0.25)
+    >>> appellf1(1,2,3,5,0.5,0.25)
+    appellf1(1, 2, 3, 5, 0.5, 0.25)
+
     References
     ==========
 
diff --git a/sympy/functions/special/spherical_harmonics.py b/sympy/functions/special/spherical_harmonics.py
index fe210f5a0bfd..cf6a4d7f73f4 100644
--- a/sympy/functions/special/spherical_harmonics.py
+++ b/sympy/functions/special/spherical_harmonics.py
@@ -262,6 +262,24 @@ def Ynm_c(n, m, theta, phi):
 
     Ynm, Znm
 
+    Examples
+    ========
+    >>> from sympy import Znm, Symbol, simplify
+    >>> from sympy.abc import n,m
+    >>> theta = Symbol("theta")
+    >>> phi = Symbol("phi")
+    >>> Znm(n, m, theta, phi)
+    Znm(n, m, theta, phi)
+
+    For specific integers n and m we can evaluate the harmonics
+    to more useful expressions:
+    >>> simplify(Znm(0, 0, theta, phi).expand(func=True))
+    1/(2*sqrt(pi))
+    >>> simplify(Znm(1, 1, theta, phi).expand(func=True))
+    -sqrt(3)*sin(theta)*cos(phi)/(2*sqrt(pi))
+    >>> simplify(Znm(2, 1, theta, phi).expand(func=True))
+    -sqrt(15)*sin(2*theta)*cos(phi)/(4*sqrt(pi))
+
     References
     ==========
 


Code review comments:
diff_hunk: @@ -1100,6 +1100,16 @@ class appellf1(Function):
         \frac{(a)_{m+n} (b_1)_m (b_2)_n}{(c)_{m+n}}
         \frac{x^m y^n}{m! n!}.
 
+    Examples
+    ========
+    >>> from sympy.functions.special.hyper import appellf1
+    >>> appellf1(2., 1., 6., 4., 5., 6.)
+    0.0063339426292673
+    >>> appellf1(1,2,3,5,0.5,0.25)
+    appellf1(1, 2, 3, 5, 0.5, 0.25)
path: sympy/functions/special/hyper.py
text: @user1:
```suggestion
    >>> appellf1(1, 2, 3, 5, 0.5, 0.25)
    appellf1(1, 2, 3, 5, 0.5, 0.25)
```

@author:
Changed.

diff_hunk: @@ -262,6 +262,24 @@ def Ynm_c(n, m, theta, phi):
 
     Ynm, Znm
 
+    Examples
+    ========
+    >>> from sympy import Znm, Symbol, simplify
+    >>> from sympy.abc import n,m
+    >>> theta = Symbol("theta")
+    >>> phi = Symbol("phi")
+    >>> Znm(n, m, theta, phi)
+    Znm(n, m, theta, phi)
+
+    For specific integers n and m we can evaluate the harmonics
+    to more useful expressions:
+    >>> simplify(Znm(0, 0, theta, phi).expand(func=True))
path: sympy/functions/special/spherical_harmonics.py
text: @user1:
```suggestion
    to more useful expressions:

    >>> simplify(Znm(0, 0, theta, phi).expand(func=True))
```

@author:
Done.