[sympy] SPHINX DOCUMENTATION. (#1499)
Angadh Nanjangud
Added 'text book' matter and api on LagrangesMethod and new functions added through the summer.
You can merge this Pull Request by running:
git pull https://github.com/angadhn/sympy Documentation
Or view, comment on, or merge it at:
https://github.com/sympy/sympy/pull/1499
Commit Summary
- SPHINX DOCUMENTATION.
File Changes
- M doc/src/modules/physics/mechanics/api/kane.rst (19)
- M doc/src/modules/physics/mechanics/api/part_bod.rst (15)
- M doc/src/modules/physics/mechanics/examples.rst (117)
- M doc/src/modules/physics/mechanics/kane.rst (216)
- M doc/src/modules/physics/mechanics/masses.rst (215)
- M doc/src/modules/physics/mechanics/reference.rst (2)
Patch Links
—
Reply to this email directly or view it on GitHub.
Angadh Nanjangud
Stefan Krastanov
SymPy Bot Summary: 
There were test failures.
@angadhn: Please fix the test failures.
Test command: setup.py test
master hash: 5569bb2
branch hash: 004a297
Interpreter 1: There were test failures.
Interpreter: /usr/local/bin/python2.5 (2.5.6-final-0)
Architecture: Linux (64-bit)
Cache: yes
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sYwfAhDA
Interpreter 2: There were test failures.
Interpreter: /usr/bin/python2.7 (2.7.3-candidate-2)
Architecture: Linux (64-bit)
Cache: yes
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sYgqQjDA
Interpreter 3: There were test failures.
Interpreter: /usr/bin/python3.2 (3.2.3-candidate-2)
Architecture: Linux (64-bit)
Cache: yes
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sY7rYiDA
Build HTML Docs: 
All tests have passed.
Docs build command: make html-errors
Sphinx version: 1.1.3
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sYtMYiDA
Automatic review by SymPy Bot.
Angadh Nanjangud
Just fixed the errors related to Lagrange. The 'Kane' examples and text need fixing though.
Stefan Krastanov
SymPy Bot Summary: There were test failures.
@angadhn: Please fix the test failures.
Test command: setup.py test
master hash: 5569bb2
branch hash: 74ff14c
Interpreter 1: There were test failures.
Interpreter: /usr/local/bin/python2.5 (2.5.6-final-0)
Architecture: Linux (64-bit)
Cache: yes
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sY04wjDA
Interpreter 2: There were test failures.
Interpreter: /usr/bin/python2.7 (2.7.3-candidate-2)
Architecture: Linux (64-bit)
Cache: yes
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sYwvAhDA
Interpreter 3: There were test failures.
Interpreter: /usr/bin/python3.2 (3.2.3-candidate-2)
Architecture: Linux (64-bit)
Cache: yes
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sY7Y8iDA
Build HTML Docs: All tests have passed.
Docs build command: make html-errors
Sphinx version: 1.1.3
Test results html report: http://reviews.sympy.org/report/agZzeW1weTNyDAsSBFRhc2sYmZwjDA
Automatic review by SymPy Bot.
—
Reply to this email directly or view it on GitHub.
Stefan Krastanov
Angadh Nanjangud
@moorepants @hazelnusse This PR for the documentation to the Lagrange stuff was opened a while back but I guess I forgot to tag you guys. Could you go over it whenver you're free? Also, the failures are w.r.t Kanes Method because of the changed interface.
Julien Rioux
SymPy Bot Summary: Failed after merging angadhn/Documentation (74ff14c) into master (c49dca1).
@angadhn: Please fix the test failures.
Python 2.7.2-final-0: fail
Python 3.2.1-final-0: fail
Sphinx 1.1.3: pass
Docs build command: make clean && make html-errors && make clean && make latex && cd _build/latex && xelatex -interaction=nonstopmode sympy-*.tex
Julien Rioux
You need to adapt to the new names for these methods. In master Kane has become KanesMethod and so on. You also need to make sure that any names you use are being imported.
Failed after merging angadhn/Documentation (Julien Rioux
Sphinx 1.1.3: 
Julien Rioux
Julien Rioux
In doc/src/modules/physics/mechanics/examples.rst:
> > +Here the rolling disc is formed from the contact point up, removing the > +need to introduce generalized speeds. Only 3 configuration and 3 > +speed variables are need to describe this system, along with the
need -> needed
Julien Rioux
In doc/src/modules/physics/mechanics/kane.rst:
> +For a constrained system with "n" generalized speeds and "m" constraints, we
> +will get n - m equations. The mass-matrix/forcing equations are then augmented
> +in the following fashion:
> +
> +.. math::
> + x = \begin{bmatrix} \ddot{q} \\ \lambda \end{bmatrix} \\
> + \mathbf{M}(q, t) &= \begin{bmatrix} \mathbf{m_d}(q, t) &
> + \mathbf{\Lambda_c}(q, t) \end{bmatrix}\\
> + \mathbf{F}(\dot{q}, q, t) &= \begin{bmatrix} \mathbf{f_d}(q, \dot{q}, t)
> + \end{bmatrix}\\
> +
> +
> +Lagrange's Method in Physics/Mechanics
> +======================================
> +
> +Formulation of the equations of motion in :mod:`mechanics` using
Formulation -> The formulation
Julien Rioux
In doc/src/modules/physics/mechanics/kane.rst:
> +It is possible to obtain the mass matrix and the forcing vector. :: > + > + >>> LM.mass_matrix > + [2, 0] > + [0, 2] > + > + >>> LM.forcing > + [0] > + [0] > + > +If there are any holonomic or non-holonomic constraints, they must be supplied > +as keyword arguments in a list of expressions which are equal to zero. It > +should be noted that :mod:`mechanics` requires that the holonomic constraint > +equations must be supplied as velocity level constraint equations i.e. the > +holonomic constraint equations must be supplied after they have been > +differentiated with respect to time. Modifyinh the example above, the equations
Modifying
Julien Rioux
Looks good, I have no more comments.
Jason Moore
I just tried to build the html docs to check this out but am getting a numpydoc error:
moorepants@moorepants-LT:doc(angadh-doc)$ make html
rm -rf sphinx
mkdir -p src/.static
mkdir -p _build/html
mkdir -p _build/doctrees
mkdir -p src/modules
PYTHONPATH=..: sphinx-build -b html -d _build/doctrees -D latex_paper_size= src _build/html
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 172 source files that are out of date
updating environment: 172 added, 0 changed, 0 removed
/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py:117: UserWarning: Unknown section Permutations Notation
/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py:117: UserWarning: Unknown section Array Notation And 2-line Form
/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py:117: UserWarning: Unknown section Disjoint Cycle Notation
/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py:117: UserWarning: Unknown section Equality Testing
/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py:117: UserWarning: Unknown section Identity Permutation
/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py:117: UserWarning: Unknown section Permutation Printing
/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py:117: UserWarning: Unknown section Short Introduction To Other Methods
reading sources... [ 16%] modules/core
Exception occurred:
File "/usr/local/lib/python2.7/dist-packages/numpydoc/docscrape.py", line 466, in __init__
ValueError: Expected a class or None, but got <function Real at 0x2810d70>
The full traceback has been saved in /tmp/sphinx-err-8pc9ZO.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.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [html] Error 1
Anyone know what I'm doing wrong?
Angadh Nanjangud
In doc/src/modules/physics/mechanics/kane.rst:
> +For a constrained system with "n" generalized speeds and "m" constraints, we
> +will get n - m equations. The mass-matrix/forcing equations are then augmented
> +in the following fashion:
> +
> +.. math::
> + x = \begin{bmatrix} \ddot{q} \\ \lambda \end{bmatrix} \\
> + \mathbf{M}(q, t) &= \begin{bmatrix} \mathbf{m_d}(q, t) &
> + \mathbf{\Lambda_c}(q, t) \end{bmatrix}\\
> + \mathbf{F}(\dot{q}, q, t) &= \begin{bmatrix} \mathbf{f_d}(q, \dot{q}, t)
> + \end{bmatrix}\\
> +
> +
> +Lagrange's Method in Physics/Mechanics
> +======================================
> +
> +Formulation of the equations of motion in :mod:`mechanics` using
Fixed both. Thanks for spotting them! good to merge, you think?
Julien Rioux
In doc/src/modules/physics/mechanics/kane.rst:
> +For a constrained system with "n" generalized speeds and "m" constraints, we
> +will get n - m equations. The mass-matrix/forcing equations are then augmented
> +in the following fashion:
> +
> +.. math::
> + x = \begin{bmatrix} \ddot{q} \\ \lambda \end{bmatrix} \\
> + \mathbf{M}(q, t) &= \begin{bmatrix} \mathbf{m_d}(q, t) &
> + \mathbf{\Lambda_c}(q, t) \end{bmatrix}\\
> + \mathbf{F}(\dot{q}, q, t) &= \begin{bmatrix} \mathbf{f_d}(q, \dot{q}, t)
> + \end{bmatrix}\\
> +
> +
> +Lagrange's Method in Physics/Mechanics
> +======================================
> +
> +Formulation of the equations of motion in :mod:`mechanics` using
I think you missed this particular line.
Angadh Nanjangud
In doc/src/modules/physics/mechanics/kane.rst:
> +For a constrained system with "n" generalized speeds and "m" constraints, we
> +will get n - m equations. The mass-matrix/forcing equations are then augmented
> +in the following fashion:
> +
> +.. math::
> + x = \begin{bmatrix} \ddot{q} \\ \lambda \end{bmatrix} \\
> + \mathbf{M}(q, t) &= \begin{bmatrix} \mathbf{m_d}(q, t) &
> + \mathbf{\Lambda_c}(q, t) \end{bmatrix}\\
> + \mathbf{F}(\dot{q}, q, t) &= \begin{bmatrix} \mathbf{f_d}(q, \dot{q}, t)
> + \end{bmatrix}\\
> +
> +
> +Lagrange's Method in Physics/Mechanics
> +======================================
> +
> +Formulation of the equations of motion in :mod:`mechanics` using
Oh. I must have undone something and forgotten about it. Sorry and thanks!!
Dale Lukas Peterson
In doc/src/modules/physics/mechanics/kane.rst:
> +.. math::
> + \mathbf{m_{c}}(q, t) \dot{q} + \mathbf{f_{c}}(q, t) &= 0\\
> + \mathbf{m_{dc}}(\dot{q}, q, t) \ddot{q} + \mathbf{f_{dc}}(\dot{q}, q, t) &= 0\\
> + \mathbf{m_d}(\dot{q}, q, t) \ddot{q} + \mathbf{\Lambda_c}(q, t)
> + \lambda + \mathbf{f_d}(\dot{q}, q, t) &= 0\\
> +
> +In this module, the expressions formed by using Lagrange's equations of the
> +second kind are rearranged into the following form:
> +
> + :math:`\mathbf{M}(q, t) x = \mathbf{f}(q, \dot{q}, t)`
> +
> +where in the case of a system without constraints:
> +
> + :math:`x = \ddot{q}`
> +
> +For a constrained system with "n" generalized speeds and "m" constraints, we
Get rid of double quotes around n and m, here and other locations. See http://www.unnecessaryquotes.com/ for further examples.
Angadh Nanjangud
In doc/src/modules/physics/mechanics/kane.rst:
> +.. math::
> + \mathbf{m_{c}}(q, t) \dot{q} + \mathbf{f_{c}}(q, t) &= 0\\
> + \mathbf{m_{dc}}(\dot{q}, q, t) \ddot{q} + \mathbf{f_{dc}}(\dot{q}, q, t) &= 0\\
> + \mathbf{m_d}(\dot{q}, q, t) \ddot{q} + \mathbf{\Lambda_c}(q, t)
> + \lambda + \mathbf{f_d}(\dot{q}, q, t) &= 0\\
> +
> +In this module, the expressions formed by using Lagrange's equations of the
> +second kind are rearranged into the following form:
> +
> + :math:`\mathbf{M}(q, t) x = \mathbf{f}(q, \dot{q}, t)`
> +
> +where in the case of a system without constraints:
> +
> + :math:`x = \ddot{q}`
> +
> +For a constrained system with "n" generalized speeds and "m" constraints, we
No single quotes either? Will fix this when I get back on Ubuntu later tonight.
Dale Lukas Peterson
In doc/src/modules/physics/mechanics/kane.rst:
> +.. math::
> + \mathbf{m_{c}}(q, t) \dot{q} + \mathbf{f_{c}}(q, t) &= 0\\
> + \mathbf{m_{dc}}(\dot{q}, q, t) \ddot{q} + \mathbf{f_{dc}}(\dot{q}, q, t) &= 0\\
> + \mathbf{m_d}(\dot{q}, q, t) \ddot{q} + \mathbf{\Lambda_c}(q, t)
> + \lambda + \mathbf{f_d}(\dot{q}, q, t) &= 0\\
> +
> +In this module, the expressions formed by using Lagrange's equations of the
> +second kind are rearranged into the following form:
> +
> + :math:`\mathbf{M}(q, t) x = \mathbf{f}(q, \dot{q}, t)`
> +
> +where in the case of a system without constraints:
> +
> + :math:`x = \ddot{q}`
> +
> +For a constrained system with "n" generalized speeds and "m" constraints, we
Jason Moore
Any suggestions for me about building the docs? I assume it builds find for you all?
Dale Lukas Peterson
@moorepants @angadhn
This built with no errors for me under Python3. I don't have an easy way to test Python 2.7 at the moment so I can't help out with the build issue @moorepants had, but I also got none of the warnings when I built. I'm using sphinx 1.1.3 and python 3.2.3.
The documentation looks good to me other than the quotation issue. I would recommend going with the inline math mode using MathJax on those variables so they stand out from the normal text.
Julien Rioux
@moorepants Sorry, it builds fine here, not sure what the problem is, assuming that you did make clean first.
@angadhn Use bacticks (`) instead of dollar signs ($). This gives you the default role, which is :math: in our documentation.
Aaron Meurer
Instead of quotes, use single backticks so that they render as latex math.
Aaron Meurer
@moorepants you seem t have the numpydoc extension installed, which messes up sphinx. Try upgrading it, or just uninstalling it.
Jason Moore
@asmeurer Thanks. I use numpydoc for other projects and have never had any issue. I have the latest pypi version, I'll see if the github repo is a newer version and upgrade. Does sympy use numpydoc styled doc strings? I had thought it does.
Jason Moore
It looks like sympy requires numpydoc:
https://github.com/sympy/sympy/blob/master/doc/src/conf.py#L25
Aaron Meurer
SymPy actually includes its own copy of numpy doc in doc/ext/. So I'm not sure why it isn't pulling in that.
Aaron Meurer
Oh, it's because of the sys.path.extend line. Clearly, we should be adding those things to the front of the path, not the back. Try changing that line in conf.py to
sys.path = ['../sympy', 'ext'] + sys.path
and see if it works.
Aaron Meurer
Oh, and now that I read it closer, the issue is obvious. We modified numpydoc to handle arbitrary section names, hence those warnings. The actual error probably corresponds to some other change we made.
Julien Rioux
Merged #1499.
Julien Rioux
Thanks, I've committed this.
Angadh Nanjangud
@jrioux thanks for the review and comments.