preliminary Mathematica like docs
Ondrej Certik
as I promised, I started to rewrite the Mathematica docs to sphinx
using Python+SymPy. You can pull from the doc branch here:
http://github.com/certik/sympy/tree/doc
and see the results here:
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/
it starts here:
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/reference.html
As you can see, Mathematica has a lot of docs.... So far the following
are ported:
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/reference/range.html
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/reference/append.html
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/reference/pi.html
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/reference/E.html
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/reference/GoldenRatio.html
http://dakol.fsik.cvut.cz/~ondra/sympy-doc/reference/EulerGamma.html
plus couple pages leading to the above. Pages the are ported are
ported fully and where SymPy cannot do it, I linked to the issue.
Currently the whole list is here:
http://code.google.com/p/sympy/issues/list?q=label:MathematicaDocs
As you can see, from 23 issues, only 2 are marked as WrongResult (e.g.
sympy returning wrong results), the rest is simply that SymPy cannot
do it. Obviously, the WrongResult ones should be fixed with higher
priority.
Let me know if you like the result. If nothing, the generated issues
are valuable, I expect there will be hundreds when I finish. Btw, if
you would like to help out, it'd be awesome. Just clone the repo above
(for example at github), translate something commit, push and I can
then just pull from you.
I notice that one can generate really cool plots, so we should
implement plotting using matplotlib using some easy to use interface.
I know Fredrik started to work on it and I really like the results so
far.
Another reason why I am doing it is to clearly define which features I
am very interested in. Basically, I want sympy to be able to do
everything here:
http://reference.wolfram.com/mathematica/guide/Mathematica.html
Of course delegate stuff to other packages, like scipy & numpy &
matplotlib (+possibly Sage notebook). When we port most of the
relevant docs, we will see the full picture what is still missing and
also we will have a clear documentation for stuff that is already in
sympy. My experience so far is that there is a *lot* of things still
missing, on the other hand, I was myself surprised how many things
already work very nicely in sympy, so I think it is definitely doable.
Ondrej
Fredrik Johansson
>
> Hi,
>
> as I promised, I started to rewrite the Mathematica docs to sphinx
> using Python+SymPy. You can pull from the doc branch here:
Careful. While creating documentation in a similar style seems
worthwhile, copying their selection of examples arguably constitutes
copyright infringement.
Fredrik
Ondrej Certik
That has not occured to me at all. Well, I could of course change the
examples, like instead of
In [1]: N(GoldenRatio, 50)
Out[1]: 1.6180339887498948482045868343656381177203091798058
use
In [1]: N(GoldenRatio, 49)
Out[1]: 1.618033988749894848204586834365638117720309179806
but I don't think this is going to help much, as clearly there is no
precise line between a new work and a derivative work. Or is it?
Well, I think the best way forward is that I just finish the job,
generate all the issues, try to use my words for all the text and then
ask Wolfram if it's ok to use their examples. If it's not ok, we'll
have to change it.
Ondrej
Ondrej Certik
Citing from:
http://www.wolfram.com/company/terms.html
Except where otherwise noted, all materials, software, and information
on the Site, as well as any unique visual or functional elements of
the Site, are copyrighted and are protected by worldwide copyright
laws and treaty provisions. They may not be copied, reproduced,
modified, uploaded, posted, transmitted, or distributed in any way, in
whole or in part, without WRI's prior written permission.
So I think I will have to stop the effort of trying to reproduce the
docs, because it is clearly forbidden without a WRI's prior written
permission. I just sent an email to Wolfram asking if we can use the
same examples as they have.
Ondrej
Ondrej Certik
>
> http://www.wolfram.com/company/terms.html
>
> Except where otherwise noted, all materials, software, and information
> on the Site, as well as any unique visual or functional elements of
> the Site, are copyrighted and are protected by worldwide copyright
> laws and treaty provisions. They may not be copied, reproduced,
> modified, uploaded, posted, transmitted, or distributed in any way, in
> whole or in part, without WRI's prior written permission.
>
>
> So I think I will have to stop the effort of trying to reproduce the
> docs, because it is clearly forbidden without a WRI's prior written
> permission. I just sent an email to Wolfram asking if we can use the
> same examples as they have.
Ok, so here is the result:
It took some time until Wolfram replied and we then exchanged couple
emails, where I described what we want and what our intention is (e.g.
having a free BSD licensed documentation), they for example asked if
we'd be willing to put a link to their website into our docs, I said
that as to me, sure, but given the nature of the BSD license, anyone
can fork sympy and take the link out, etc. I also asked how exactly
our docs can be similar to theirs (e.g. can we use the same examples,
changed examples, same structure, changed structure, ...). I cannot
cite their reply, as it is considered confidential, but I can say it
using my words:
They appreciate our effort asking them first and answering their
questions and that they have invested a lot of time and resources into
their docs and they consider it to be one of the unique attibutes of
Mathematica, so they cannot grant us to use the exact same structure
and/or examples as they have it, even if the language is changed from
Mathematica to Python. However, they are not opposed to more limited
usage if the structure and examples are sufficiently different -- they
don't have any specific guidelines or policies for that yet, so they
invite us to propose a modified format sufficiently different from
Mathematica's, to alleviate their concerns but still providing the
benefits we want.
So I think that's a fair answer. My original plan, that we will just
translate the exact things to sympy, but keep the structure and
examples the same will not work. Instead, let's write everything
ourselves and do our own examples and our structure, only keep
inspired by the Mathematica's documentation (but do not copy anything)
and we should be fine.
I hope to start working on that again, because good docs are badly needed.
Ondrej
Gael Varoquaux
> So I think that's a fair answer.
+1. It sounds like they acted pretty civilized here.
Gaël
Fredrik Johansson
I agree.
On a related note, I've started writing more extensive documentation
for all the functions in mpmath. Sphinx recently got support for LaTeX
equations, so now it's possible to mix the Python code examples with
beautifully typeset formulas to explain what's going on :-)
See the current progress here:
http://mpmath.googlecode.com/svn/trunk/doc/build/functions/index.html
The structure and style is very much inspired by the Mathematica docs,
but all text and examples are original.
Fredrik
Ondrej Certik
<fredrik....@gmail.com> wrote:
>
> On Sat, Nov 15, 2008 at 11:14 PM, Gael Varoquaux
> <gael.va...@normalesup.org> wrote:
>>
>> On Sat, Nov 15, 2008 at 11:11:05PM +0100, Ondrej Certik wrote:
>>> So I think that's a fair answer.
>>
>> +1. It sounds like they acted pretty civilized here.
>>
>> Gaël
>
> I agree.
Yep. I like that I asked directly what we want, without hiding
anything, and they say what they want, also without hiding anything
and also that they actually found time to answer.
>
> On a related note, I've started writing more extensive documentation
> for all the functions in mpmath. Sphinx recently got support for LaTeX
> equations, so now it's possible to mix the Python code examples with
> beautifully typeset formulas to explain what's going on :-)
>
> See the current progress here:
>
> http://mpmath.googlecode.com/svn/trunk/doc/build/functions/index.html
>
> The structure and style is very much inspired by the Mathematica docs,
> but all text and examples are original.
This looks really excellent! Would you be willing to help me with the
sympy documentation? You have much better talent for it, than I do.
Also about the plotting stuff --- the mpmath plotting code really
produces nice pictures
http://mpmath.googlecode.com/svn/gallery/gallery.html
so I think we should go this way with sympy as well, at least in 2D.
Ondrej
Fredrik Johansson
> This looks really excellent! Would you be willing to help me with the
> sympy documentation? You have much better talent for it, than I do.
If only I had the time to do that also :-/
> Also about the plotting stuff --- the mpmath plotting code really
> produces nice pictures
>
> http://mpmath.googlecode.com/svn/gallery/gallery.html
>
> so I think we should go this way with sympy as well, at least in 2D.
It would be nice if one could set it up so that any plotting example
in a docstring automatically saves to a file (and adds it to the HTML
output) when doctest is run. I think this can be accomplished, but I'm
not sure how to do it in the details.
Fredrik
Andy R. Terrel
really difficult, it seems with the little documentation there is I
find errors. Is it worth thinking about how to get some of this
automated from the module doc strings?
-- Andy
Ondrej Certik
Yes, I think we should test it automatically. Right now I am improving
our doctests, so that they run without py.test and also improving how
the output looks like. Then I suggest we simply greatly improve our
doctests and generate most of the documentation using docstrings,
sphinx can do that.
Ondrej
Alan Bromborsky
a first effort. Comments? Also a comment about documentation. Before
retiring I had to write technical reports about scientific research
(often containing descriptions of software developed for the research).
I found that if I did not generate the documentation as the research
(code development) progressed (for example write a function and document
it immediately) the documentation either did not get done or was of poor
quality. One of the biggest grips I had about the technical reports
that resulted from projects that the agency I was in funded was the poor
quality of the documentation of the software developed by those projects
(of course the contractors may have just been trying to keep the
software unusable for anyone outside of there company). From the
viewpoint of a contracting agent I would say that good software
documentation cost most than actually developing the software itself!
Andy Ray Terrel
Do you have the code that generated this somewhere that I could pull
it and have a look?
-- Andy
> >
>
Alan Bromborsky
http://www.python.org/doc/2.5.2/doc/doc.html
The actual style files are included with the python distribution and
have to be put in the LaTeX path.
I am attaching the latex files I wrote to generate the previous example
(they were processed with pdflatex)